From 258a216e543c00196f26c50ded435c5195bd2c0a Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 16:34:04 +0800
Subject: [PATCH 01/13] =?UTF-8?q?feat(go):=20Phase=200+1=20=E2=80=94=20Go?=
 =?UTF-8?q?=20=E9=87=8D=E5=86=99=E5=9C=B0=E5=9F=BA=E4=B8=8E=E6=A0=B8?=
 =?UTF-8?q?=E5=BF=83=20CLI=EF=BC=8Cnpm=20=E5=88=86=E5=8F=91=20Go=20?=
 =?UTF-8?q?=E4=BA=8C=E8=BF=9B=E5=88=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 0：Go 骨架 + npm 分发管道
- cobra root（--version/--help/NoArgs），ldflags 注入版本
- npm launcher（require.resolve 平台子包二进制并 spawn 透传 exit code）
- scripts/build-go.sh：交叉编译 5 平台（darwin/linux x64+arm64、win32 x64）
  → dist-native/ 原始二进制 + dist-npm/ 主包(optionalDependencies)+平台子包(os/cpu)
- scripts/gen-pkg.mjs 生成各包 package.json

Phase 1：地基层 + 核心命令（端到端验证）
- errs/fsutil/paths/config：错误码、原子写、目录布局、schema
  （json.Unmarshal 覆盖默认值复现 deepMerge；点号路径 get/set/unset/coerce/mask）
- keychain/creds：security|secret-tool shell-out；env/file/keychain/inline 引用；
  api-key 分层解析 + multi-key + gateway token（忠实移植 store.ts）
- notif：通知查询匹配 + app 中英文别名 + date-key 收集（读侧）
- output/clictx/prompt/daemon(lock 读侧)：json|pretty|table|ndjson 输出对齐 JS
- cli：handler wrapper + 全局 flags + config/profile/auth/notification/doctor

与现有 TS 实现同仓共存，不影响现有 npm 发布线（并行重写策略）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .gitignore                       |   5 +
 cmd/yc/main.go                   |  11 +
 go.mod                           |  10 +
 go.sum                           |  10 +
 internal/cli/cmd_auth.go         | 218 ++++++++++++++
 internal/cli/cmd_config.go       | 216 ++++++++++++++
 internal/cli/cmd_doctor.go       | 128 +++++++++
 internal/cli/cmd_notification.go | 327 +++++++++++++++++++++
 internal/cli/cmd_profile.go      | 120 ++++++++
 internal/cli/handler.go          |  76 +++++
 internal/cli/root.go             |  46 +++
 internal/clictx/clictx.go        |  50 ++++
 internal/config/config.go        | 180 ++++++++++++
 internal/config/dotpath.go       | 182 ++++++++++++
 internal/creds/refs.go           | 140 +++++++++
 internal/creds/store.go          | 478 +++++++++++++++++++++++++++++++
 internal/daemon/lock.go          |  46 +++
 internal/daemon/proc_unix.go     |  20 ++
 internal/daemon/proc_windows.go  |  15 +
 internal/errs/errors.go          |  80 ++++++
 internal/fsutil/fsutil.go        |  95 ++++++
 internal/keychain/keychain.go    |  84 ++++++
 internal/notif/query.go          | 303 ++++++++++++++++++++
 internal/notif/types.go          |  41 +++
 internal/output/output.go        | 201 +++++++++++++
 internal/paths/paths.go          | 109 +++++++
 internal/prompt/prompt.go        |  79 +++++
 internal/version/version.go      |  11 +
 npm/cli/README.md                |  23 ++
 npm/cli/bin/yc.js                |  43 +++
 scripts/build-go.sh              |  82 ++++++
 scripts/gen-pkg.mjs              |  52 ++++
 32 files changed, 3481 insertions(+)
 create mode 100644 cmd/yc/main.go
 create mode 100644 go.mod
 create mode 100644 go.sum
 create mode 100644 internal/cli/cmd_auth.go
 create mode 100644 internal/cli/cmd_config.go
 create mode 100644 internal/cli/cmd_doctor.go
 create mode 100644 internal/cli/cmd_notification.go
 create mode 100644 internal/cli/cmd_profile.go
 create mode 100644 internal/cli/handler.go
 create mode 100644 internal/cli/root.go
 create mode 100644 internal/clictx/clictx.go
 create mode 100644 internal/config/config.go
 create mode 100644 internal/config/dotpath.go
 create mode 100644 internal/creds/refs.go
 create mode 100644 internal/creds/store.go
 create mode 100644 internal/daemon/lock.go
 create mode 100644 internal/daemon/proc_unix.go
 create mode 100644 internal/daemon/proc_windows.go
 create mode 100644 internal/errs/errors.go
 create mode 100644 internal/fsutil/fsutil.go
 create mode 100644 internal/keychain/keychain.go
 create mode 100644 internal/notif/query.go
 create mode 100644 internal/notif/types.go
 create mode 100644 internal/output/output.go
 create mode 100644 internal/paths/paths.go
 create mode 100644 internal/prompt/prompt.go
 create mode 100644 internal/version/version.go
 create mode 100644 npm/cli/README.md
 create mode 100644 npm/cli/bin/yc.js
 create mode 100755 scripts/build-go.sh
 create mode 100644 scripts/gen-pkg.mjs

diff --git a/.gitignore b/.gitignore
index 03577fc..a2e7544 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,9 +4,14 @@ node_modules
 # 构建产物
 dist
 dist-native
+dist-npm
 *.tgz
 *.tsbuildinfo
 
+# Go（本地散落的二进制；go vendor 用 /vendor 顶层，勿用裸 vendor 误伤 src/vendor）
+/yc
+/vendor/
+
 # 环境变量与密钥
 .env
 .env.local
diff --git a/cmd/yc/main.go b/cmd/yc/main.go
new file mode 100644
index 0000000..e51d654
--- /dev/null
+++ b/cmd/yc/main.go
@@ -0,0 +1,11 @@
+// Command yc 是 yoooclaw CLI 的 Go 实现入口。
+//
+// 真实命令树与业务实现在 internal/cli 下逐步补齐（见 Go 重写计划 Phase 1+）；
+// 本文件只负责装配 root 命令并执行。
+package main
+
+import "github.com/YoooClaw/cli/internal/cli"
+
+func main() {
+	cli.Execute()
+}
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..f950f13
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,10 @@
+module github.com/YoooClaw/cli
+
+go 1.26.4
+
+require github.com/spf13/cobra v1.10.2
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..a6ee3e0
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,10 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
diff --git a/internal/cli/cmd_auth.go b/internal/cli/cmd_auth.go
new file mode 100644
index 0000000..8e4880a
--- /dev/null
+++ b/internal/cli/cmd_auth.go
@@ -0,0 +1,218 @@
+package cli
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/daemon"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/prompt"
+	"github.com/spf13/cobra"
+)
+
+func newAuthCmd() *cobra.Command {
+	c := &cobra.Command{Use: "auth", Short: "凭据与鉴权 🟢/🟡"}
+
+	setKey := &cobra.Command{Use: "set-api-key <key>", Short: "设置/轮换 account 级 default api-key（- 从 stdin 读）🟢", Args: cobra.ExactArgs(1), RunE: run(authSetAPIKey)}
+	setKey.Flags().Bool("keychain", false, "写入 OS keychain 而非文件")
+
+	addKey := &cobra.Command{Use: "add-api-key <key>", Short: "新增一条 multi-key api-key（- 从 stdin 读）🟢", Args: cobra.ExactArgs(1), RunE: run(authAddAPIKey)}
+	addKey.Flags().String("label", "", "api-key label（[a-z0-9-]{1,32}）")
+	addKey.Flags().Bool("default", false, "设为 default key")
+	addKey.Flags().Bool("force", false, "label 已存在时覆盖")
+
+	listKeys := &cobra.Command{Use: "list-api-keys", Short: "列出 api-key 条目（key 自动遮罩）🟢", Args: cobra.NoArgs, RunE: run(authListAPIKeys)}
+	rmKey := &cobra.Command{Use: "remove-api-key <label>", Short: "删除指定 label 的 api-key 🟢", Args: cobra.ExactArgs(1), RunE: run(authRemoveAPIKey)}
+	setDefault := &cobra.Command{Use: "set-default-api-key <label>", Short: "切换 default api-key 🟢", Args: cobra.ExactArgs(1), RunE: run(authSetDefaultAPIKey)}
+
+	rotate := &cobra.Command{Use: "token-rotate", Short: "生成新 gateway token；daemon 在跑时随后 restart 生效 🟢", Args: cobra.NoArgs, RunE: run(authTokenRotate)}
+	rotate.Flags().String("length", "32", "token 字节长度")
+
+	status := &cobra.Command{Use: "status", Short: "显示鉴权状态（本地检查，不调 daemon）🟢", Args: cobra.NoArgs, RunE: run(authStatus)}
+	check := &cobra.Command{Use: "check", Short: "端到端鉴权体检（调 daemon /daemon/status）🟡", Args: cobra.NoArgs, RunE: run(authCheck)}
+
+	c.AddCommand(setKey, addKey, listKeys, rmKey, setDefault, rotate, status, check)
+	return c
+}
+
+func readKeyArg(arg string) (string, error) {
+	if arg == "-" {
+		s, err := prompt.ReadStdin()
+		if err != nil {
+			return "", err
+		}
+		arg = strings.TrimSpace(s)
+	}
+	if arg == "" {
+		return "", errs.New(errs.CodeInvalidArgument, "api-key 不能为空")
+	}
+	return arg, nil
+}
+
+func authSetAPIKey(_ *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	key, err := readKeyArg(args[0])
+	if err != nil {
+		return nil, err
+	}
+	result, err := creds.SetAPIKey(key, flagBool(cmd, "keychain"))
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"ok": true, "source": result.Source, "location": result.Location, "label": result.Label,
+		"masked": creds.MaskSecret(result.Value),
+		"hint":   "插件 / CLI / daemon 共用同一份；daemon 在跑时会经文件 watch 热生效",
+	}, nil
+}
+
+func authAddAPIKey(_ *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	key, err := readKeyArg(args[0])
+	if err != nil {
+		return nil, err
+	}
+	label := flagStr(cmd, "label")
+	if label == "" {
+		return nil, errs.New(errs.CodeInvalidArgument, "--label 必填")
+	}
+	before := creds.ResolveAPIKeyEntries()
+	result, err := creds.AddAPIKey(key, label, flagBool(cmd, "default"), flagBool(cmd, "force"))
+	if err != nil {
+		return nil, err
+	}
+	after := creds.ResolveAPIKeyEntries()
+	isDefault := after.DefaultEntry != nil && after.DefaultEntry.Label == label
+	return map[string]any{
+		"ok": true, "mode": after.Mode, "label": label, "default": isDefault,
+		"source": result.Source, "location": result.Location, "masked": creds.MaskSecret(key),
+		"shadowedKeychainPresent": after.ShadowedKeychainPresent,
+		"migratedLegacyApiKey":    before.Mode == "legacy-file-single",
+		"hint":                    "daemon 在跑时会经文件 watch 热生效；watch 不可靠时执行 yc daemon reload",
+	}, nil
+}
+
+func entryToItem(e creds.ApiKeyEntry) map[string]any {
+	return map[string]any{"label": e.Label, "default": e.Default, "source": e.Source, "masked": creds.MaskSecret(e.Key)}
+}
+
+func entriesToItems(entries []creds.ApiKeyEntry) []any {
+	out := make([]any, 0, len(entries))
+	for _, e := range entries {
+		out = append(out, entryToItem(e))
+	}
+	return out
+}
+
+func defaultLabelOrNil(set creds.CredentialSet) any {
+	if set.DefaultEntry != nil {
+		return set.DefaultEntry.Label
+	}
+	return nil
+}
+
+func authListAPIKeys(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	set := creds.ResolveAPIKeyEntries()
+	return map[string]any{
+		"ok": true, "mode": set.Mode, "defaultLabel": defaultLabelOrNil(set), "location": set.Location,
+		"legacyApiKeyPresent": set.LegacyAPIKeyPresent, "shadowedKeychainPresent": set.ShadowedKeychainPresent,
+		"warnings": set.Warnings, "items": entriesToItems(set.Entries),
+	}, nil
+}
+
+func authRemoveAPIKey(_ *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	label := args[0]
+	_, removed, newDefault, err := creds.RemoveAPIKey(label)
+	if err != nil {
+		return nil, err
+	}
+	set := creds.ResolveAPIKeyEntries()
+	var nd any
+	if newDefault != "" {
+		nd = newDefault
+	}
+	return map[string]any{
+		"ok": true, "removed": removed, "mode": set.Mode, "defaultLabel": defaultLabelOrNil(set),
+		"newDefault": nd, "remaining": len(set.Entries),
+	}, nil
+}
+
+func authSetDefaultAPIKey(_ *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	result, err := creds.SetDefaultAPIKey(args[0])
+	if err != nil {
+		return nil, err
+	}
+	set := creds.ResolveAPIKeyEntries()
+	return map[string]any{
+		"ok": true, "mode": set.Mode, "defaultLabel": defaultLabelOrNil(set),
+		"source": result.Source, "location": result.Location,
+	}, nil
+}
+
+func authStatus(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	apiKey := creds.ResolveAPIKey()
+	apiKeys := creds.ResolveAPIKeyEntries()
+	var tokenInfo map[string]any
+	if config.Exists(ctx.Paths) {
+		cfg, err := config.Load(ctx.Paths)
+		if err == nil {
+			token, _ := creds.ResolveGatewayToken(cfg)
+			tokenInfo = map[string]any{"present": token.Value != "", "source": token.Source, "location": token.Location, "masked": creds.MaskSecret(token.Value)}
+		}
+	}
+	if tokenInfo == nil {
+		tokenInfo = map[string]any{"present": false}
+	}
+	state := daemon.State(ctx.Paths)
+	daemonInfo := map[string]any{"running": state.Running, "stale": state.Stale}
+	if state.Lock != nil {
+		daemonInfo["pid"] = state.Lock.PID
+	}
+	return map[string]any{
+		"ok": true, "profile": ctx.Profile, "mode": apiKeys.Mode, "defaultLabel": defaultLabelOrNil(apiKeys),
+		"apiKeys": entriesToItems(apiKeys.Entries), "legacyApiKeyPresent": apiKeys.LegacyAPIKeyPresent,
+		"shadowedKeychainPresent": apiKeys.ShadowedKeychainPresent, "warnings": apiKeys.Warnings,
+		"apiKey": map[string]any{
+			"present": apiKey.Value != "", "source": apiKey.Source, "location": apiKey.Location,
+			"label": apiKey.Label, "masked": creds.MaskSecret(apiKey.Value),
+		},
+		"gatewayToken": tokenInfo,
+		"daemon":       daemonInfo,
+	}, nil
+}
+
+func authTokenRotate(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	if !config.Exists(ctx.Paths) {
+		return nil, errs.New(errs.CodeConfigInvalid, "profile `"+ctx.Profile+"` 尚未初始化",
+			map[string]any{"hint": "先运行 yoooclaw config init"})
+	}
+	cfg, err := config.Load(ctx.Paths)
+	if err != nil {
+		return nil, err
+	}
+	numBytes := 32
+	if s := flagStr(cmd, "length"); s != "" {
+		n, convErr := strconv.Atoi(s)
+		if convErr != nil || n < 16 {
+			return nil, errs.New(errs.CodeInvalidArgument, "--length 至少 16 字节")
+		}
+		numBytes = n
+	}
+	token := creds.GenerateToken(numBytes)
+	written, err := creds.WriteGatewayToken(cfg, token)
+	if err != nil {
+		return nil, err
+	}
+	state := daemon.State(ctx.Paths)
+	hot := "daemon 未运行：下次启动即用新 token"
+	if state.Running {
+		hot = "daemon 在运行：请执行 yoooclaw daemon restart 使新 token 生效"
+	}
+	return map[string]any{"ok": true, "token": token, "source": written.Source, "location": written.Location, "hint": hot}, nil
+}
+
+func authCheck(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	// 端到端体检需要 daemon HTTP client，Phase 2 接入。
+	return nil, errs.NotImplemented("auth check")
+}
diff --git a/internal/cli/cmd_config.go b/internal/cli/cmd_config.go
new file mode 100644
index 0000000..26b3adb
--- /dev/null
+++ b/internal/cli/cmd_config.go
@@ -0,0 +1,216 @@
+package cli
+
+import (
+	"encoding/json"
+	"os"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/prompt"
+	"github.com/spf13/cobra"
+)
+
+func newConfigCmd() *cobra.Command {
+	c := &cobra.Command{Use: "config", Short: "配置管理 🟢"}
+
+	initCmd := &cobra.Command{
+		Use:   "init",
+		Short: "交互式首次向导，生成 config + gateway token 并启动 daemon",
+		Args:  cobra.NoArgs,
+		RunE:  run(configInit),
+	}
+	initCmd.Flags().Bool("non-interactive", false, "跳过向导（配合 --from-file）")
+	initCmd.Flags().String("from-file", "", "从 JSON 文件导入配置（- 为 stdin）")
+	initCmd.Flags().Bool("force", false, "已存在 config 时覆盖")
+	initCmd.Flags().Bool("no-start", false, "只生成配置，不自动启动 daemon")
+
+	showCmd := &cobra.Command{Use: "show", Short: "显示当前 profile 配置（敏感字段遮罩）", Args: cobra.NoArgs, RunE: run(configShow)}
+	showCmd.Flags().Bool("show-secrets", false, "输出敏感字段明文（需 TTY）")
+
+	setCmd := &cobra.Command{Use: "set <key> <value>", Short: "设置单个配置项（点号路径）", Args: cobra.ExactArgs(2), RunE: run(configSet)}
+	unsetCmd := &cobra.Command{Use: "unset <key>", Short: "删除单个配置项", Args: cobra.ExactArgs(1), RunE: run(configUnset)}
+
+	c.AddCommand(initCmd, showCmd, setCmd, unsetCmd)
+	return c
+}
+
+type initOpts struct {
+	force          bool
+	nonInteractive bool
+	fromFile       string
+	noStart        bool
+}
+
+func configInit(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	return initCore(ctx, initOpts{
+		force:          flagBool(cmd, "force"),
+		nonInteractive: flagBool(cmd, "non-interactive"),
+		fromFile:       flagStr(cmd, "from-file"),
+		noStart:        flagBool(cmd, "no-start"),
+	})
+}
+
+func initCore(ctx *clictx.Context, o initOpts) (any, error) {
+	force := o.force
+	if config.Exists(ctx.Paths) && !force {
+		return nil, errs.New(errs.CodeAlreadyExists, "profile `"+ctx.Profile+"` 已初始化",
+			map[string]any{"hint": "加 --force 覆盖，或换一个 --profile", "checkedPaths": []string{ctx.Paths.Config}})
+	}
+	if err := fsutil.EnsureDir(ctx.Paths.Dir, fsutil.DirMode); err != nil {
+		return nil, err
+	}
+	cfg := config.Default(ctx.Paths.Credentials)
+
+	nonInteractive := o.nonInteractive
+	fromFile := o.fromFile
+	if nonInteractive || !prompt.IsInteractive() {
+		if fromFile == "" {
+			return nil, errs.New(errs.CodeNotInteractive, "非交互模式必须提供 --from-file <config.json>（- 为 stdin）")
+		}
+		raw, err := readConfigImport(fromFile)
+		if err != nil {
+			return nil, err
+		}
+		// 覆盖默认结构体 = deepMerge 语义；随后 version 回到默认。
+		if err := json.Unmarshal(raw, &cfg); err != nil {
+			return nil, errs.New(errs.CodeInvalidArgument, "无法解析配置文件："+fromFile)
+		}
+		cfg.Version = config.ConfigVersion
+	} else {
+		existing := creds.ResolveAPIKey()
+		if existing.Value != "" {
+			os.Stderr.WriteString("已检测到 Relay api-key（来源 " + existing.Source + "），跳过设置\n")
+		} else {
+			key, err := prompt.Ask("Relay api-key（ock_… ，留空可稍后 yc auth set-api-key 设置）", "")
+			if err != nil {
+				return nil, err
+			}
+			if key != "" {
+				if _, err := creds.SetAPIKey(key, false); err != nil {
+					return nil, err
+				}
+			}
+		}
+		enableEval, err := prompt.Confirm("启用灯效 webhook 评估器？", false)
+		if err != nil {
+			return nil, err
+		}
+		if enableEval {
+			ev := config.DefaultEvaluator(ctx.Paths.Credentials)
+			url, err := prompt.Ask("评估器 webhook URL", "")
+			if err != nil {
+				return nil, err
+			}
+			ev.WebhookURL = url
+			cfg.LightRules.Evaluator = &ev
+		}
+	}
+
+	token := creds.GenerateToken(32)
+	if err := config.Save(ctx.Paths, cfg); err != nil {
+		return nil, err
+	}
+	if _, err := creds.WriteGatewayToken(cfg, token); err != nil {
+		return nil, err
+	}
+
+	// daemon 自动拉起在 Phase 2 接入；此处只生成配置并报告未启动。
+	apiKey := creds.ResolveAPIKey()
+	daemonInfo := map[string]any{"started": false, "note": "daemon 自动启动将在 Phase 2 接入；当前可手动 yc daemon start（Phase 2）"}
+	hint := "配置已就绪：Phase 2 接入 daemon 后即可 yc daemon start 并连上 Relay"
+	if apiKey.Value == "" {
+		hint = "配置已就绪：运行 yc auth set-api-key <ock_…> 设置 Relay api-key"
+	}
+	return map[string]any{
+		"ok":      true,
+		"profile": ctx.Profile,
+		"daemon":  daemonInfo,
+		"relay": map[string]any{
+			"url":           cfg.Relay.URL,
+			"enabled":       cfg.Relay.Enabled,
+			"apiKeyPresent": apiKey.Value != "",
+		},
+		"gatewayToken": token,
+		"configPath":   ctx.Paths.Config,
+		"hint":         hint,
+	}, nil
+}
+
+func readConfigImport(fromFile string) ([]byte, error) {
+	if fromFile == "-" {
+		s, err := prompt.ReadStdin()
+		if err != nil {
+			return nil, err
+		}
+		return []byte(s), nil
+	}
+	raw, err := os.ReadFile(fromFile)
+	if err != nil {
+		return nil, errs.New(errs.CodeInvalidArgument, "无法读取配置文件："+fromFile)
+	}
+	return raw, nil
+}
+
+func configShow(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	if !config.Exists(ctx.Paths) {
+		return nil, errs.New(errs.CodeConfigInvalid, "profile `"+ctx.Profile+"` 尚未初始化",
+			map[string]any{"hint": "先运行 yoooclaw config init", "checkedPaths": []string{ctx.Paths.Config}})
+	}
+	cfg, err := config.Load(ctx.Paths)
+	if err != nil {
+		return nil, err
+	}
+	if flagBool(cmd, "show-secrets") {
+		if !prompt.IsInteractive() {
+			return nil, errs.New(errs.CodeNotInteractive, "--show-secrets 需要在 TTY 中运行")
+		}
+		ok, err := prompt.Confirm("确认明文输出敏感字段？", false)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			return nil, errs.New(errs.CodeConfirmationRequired, "已取消")
+		}
+		return config.ToMap(cfg), nil
+	}
+	return config.Mask(config.ToMap(cfg)), nil
+}
+
+func configSet(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	key, value := args[0], args[1]
+	if key == "version" {
+		return nil, errs.New(errs.CodeInvalidArgument, "version 字段不可修改")
+	}
+	m, err := config.LoadMergedMap(ctx.Paths)
+	if err != nil {
+		return nil, err
+	}
+	coerced, err := config.CoerceValue(key, value)
+	if err != nil {
+		return nil, err
+	}
+	config.SetByPath(m, key, coerced)
+	if err := config.SaveRaw(ctx.Paths, m); err != nil {
+		return nil, err
+	}
+	got, _ := config.GetByPath(m, key)
+	return map[string]any{"ok": true, "key": key, "value": got}, nil
+}
+
+func configUnset(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	key := args[0]
+	m, err := config.LoadMergedMap(ctx.Paths)
+	if err != nil {
+		return nil, err
+	}
+	removed := config.UnsetByPath(m, key)
+	if removed {
+		if err := config.SaveRaw(ctx.Paths, m); err != nil {
+			return nil, err
+		}
+	}
+	return map[string]any{"ok": true, "key": key, "removed": removed}, nil
+}
diff --git a/internal/cli/cmd_doctor.go b/internal/cli/cmd_doctor.go
new file mode 100644
index 0000000..e7dbd0a
--- /dev/null
+++ b/internal/cli/cmd_doctor.go
@@ -0,0 +1,128 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/daemon"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/keychain"
+	"github.com/YoooClaw/cli/internal/paths"
+	"github.com/YoooClaw/cli/internal/version"
+	"github.com/spf13/cobra"
+)
+
+func newDoctorCmd() *cobra.Command {
+	c := &cobra.Command{Use: "doctor", Short: "本地环境自检：运行时/目录/keychain/config/daemon 🟢", Args: cobra.NoArgs, RunE: run(doctor)}
+	c.Flags().Bool("json", false, "JSON 输出（给脚本用）")
+	c.Flags().Bool("fix", false, "自动修复可修复的问题")
+	return c
+}
+
+type check struct {
+	Name   string `json:"name"`
+	Status string `json:"status"` // ok | warn | fail | skip
+	Detail string `json:"detail"`
+}
+
+func checkDir(name, dir string, fix bool) check {
+	if !fsutil.Exists(dir) {
+		if fix {
+			if err := fsutil.EnsureDir(dir, fsutil.DirMode); err == nil {
+				return check{name, "ok", "已创建 " + dir}
+			}
+		}
+		return check{name, "warn", "目录不存在：" + dir + "（--fix 可创建）"}
+	}
+	probe := filepath.Join(dir, ".yc-doctor-probe")
+	if err := os.WriteFile(probe, []byte("x"), 0o600); err != nil {
+		return check{name, "fail", "目录不可读写：" + dir}
+	}
+	_ = os.Remove(probe)
+	info, err := os.Stat(dir)
+	if err != nil {
+		return check{name, "fail", "无法 stat：" + dir}
+	}
+	mode := info.Mode().Perm()
+	tooOpen := mode&0o077 != 0
+	detail := dir + "（mode " + strconv.FormatUint(uint64(mode), 8) + ")"
+	if tooOpen {
+		return check{name, "warn", dir + "（mode " + strconv.FormatUint(uint64(mode), 8) + "，建议收紧到 700）"}
+	}
+	return check{name, "ok", detail}
+}
+
+func doctor(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	fix := flagBool(cmd, "fix")
+	checks := []check{
+		{"runtime", "ok", "原生二进制 " + version.Version + "（" + runtime.GOOS + "/" + runtime.GOARCH + "，无 Node 依赖）"},
+		checkDir("root-dir", paths.RootDir(), fix),
+	}
+
+	if config.Exists(ctx.Paths) {
+		if _, err := config.Load(ctx.Paths); err != nil {
+			checks = append(checks, check{"profile-config", "fail", err.Error()})
+		} else {
+			checks = append(checks, check{"profile-config", "ok", ctx.Paths.Config + " 可解析"})
+		}
+	} else {
+		checks = append(checks, check{"profile-config", "warn", "profile `" + ctx.Profile + "` 未初始化（yoooclaw config init）"})
+	}
+
+	apiKey := creds.ResolveAPIKey()
+	if apiKey.Value != "" {
+		checks = append(checks, check{"api-key", "ok", "来源 " + apiKey.Source})
+	} else {
+		checks = append(checks, check{"api-key", "warn", "未配置（yoooclaw auth set-api-key）"})
+	}
+
+	if config.Exists(ctx.Paths) {
+		if cfg, err := config.Load(ctx.Paths); err == nil {
+			token, _ := creds.ResolveGatewayToken(cfg)
+			if token.Value != "" {
+				checks = append(checks, check{"gateway-token", "ok", "来源 " + token.Source})
+			} else {
+				checks = append(checks, check{"gateway-token", "warn", "未设置（yoooclaw auth token-rotate）"})
+			}
+		}
+	}
+
+	if keychain.Available() {
+		checks = append(checks, check{"keychain", "ok", "可用"})
+	} else {
+		checks = append(checks, check{"keychain", "skip", "当前平台无可用 keychain，凭据将落文件"})
+	}
+
+	state := daemon.State(ctx.Paths)
+	switch {
+	case state.Running:
+		checks = append(checks, check{"daemon", "ok", "运行中（pid " + strconv.Itoa(state.Lock.PID) + "）"})
+	case state.Stale:
+		checks = append(checks, check{"daemon", "warn", "锁文件存在但进程已死（陈旧锁）"})
+	default:
+		checks = append(checks, check{"daemon", "skip", "未运行"})
+	}
+
+	failed, warned := 0, 0
+	checksAny := make([]any, 0, len(checks))
+	for _, c := range checks {
+		if c.Status == "fail" {
+			failed++
+		}
+		if c.Status == "warn" {
+			warned++
+		}
+		checksAny = append(checksAny, map[string]any{"name": c.Name, "status": c.Status, "detail": c.Detail})
+	}
+	return map[string]any{
+		"ok": failed == 0, "profile": ctx.Profile,
+		"summary": map[string]any{"total": len(checks), "failed": failed, "warned": warned},
+		"checks":  checksAny,
+		"note":    "网络类自检（relay / OSS 可达性）请用 yoooclaw gateway test / tunnel +test",
+	}, nil
+}
diff --git a/internal/cli/cmd_notification.go b/internal/cli/cmd_notification.go
new file mode 100644
index 0000000..89d5701
--- /dev/null
+++ b/internal/cli/cmd_notification.go
@@ -0,0 +1,327 @@
+package cli
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/notif"
+	"github.com/spf13/cobra"
+)
+
+// maxLimit 充当 summary/stats 的"全部"上限（对齐 TS 的 MAX_SAFE_INTEGER 语义）。
+const maxLimit = 1 << 60
+
+func addQueryFlags(cmd *cobra.Command) {
+	f := cmd.Flags()
+	f.String("from", "", "开始时间，如 2026-03-01T09:00:00+08:00")
+	f.String("to", "", "结束时间")
+	f.String("app", "", "按应用过滤（支持中英文别名）")
+	f.String("sender", "", "按发送人/标题过滤")
+	f.String("conversation-type", "", "会话类型 group|private")
+	f.String("keyword", "", "在标题/内容/发送人/会话名中搜索")
+	f.String("client", "", "按 clientLabel 过滤；all 为全部")
+	f.String("limit", "100", "最大返回条数")
+}
+
+func rawQueryFromCmd(cmd *cobra.Command) notif.RawQueryOpts {
+	return notif.RawQueryOpts{
+		From: flagStr(cmd, "from"), To: flagStr(cmd, "to"), App: flagStr(cmd, "app"),
+		Sender: flagStr(cmd, "sender"), ConversationType: flagStr(cmd, "conversation-type"),
+		Keyword: flagStr(cmd, "keyword"), Client: flagStr(cmd, "client"), Limit: flagStr(cmd, "limit"),
+	}
+}
+
+func newNotificationCmd() *cobra.Command {
+	c := &cobra.Command{Use: "notification", Short: "通知查询 🟢"}
+
+	search := &cobra.Command{Use: "search", Short: "按筛选条件查询通知，时间倒序", Args: cobra.NoArgs, RunE: run(notificationSearch)}
+	addQueryFlags(search)
+
+	summary := &cobra.Command{Use: "summary", Short: "聚合统计 + 样例摘要，供 Agent 总结", Args: cobra.NoArgs, RunE: run(notificationSummary)}
+	addQueryFlags(summary)
+	summary.Flags().String("sample", "30", "返回最近样例条数")
+	summary.Flags().String("top", "10", "聚合榜单条数")
+
+	stats := &cobra.Command{Use: "stats", Short: "按维度聚合统计", Args: cobra.NoArgs, RunE: run(notificationStats)}
+	stats.Flags().String("from", "", "YYYY-MM-DD 或 ISO 8601，默认 7 天前")
+	stats.Flags().String("to", "", "YYYY-MM-DD 或 ISO 8601，默认今天")
+	stats.Flags().String("app", "", "仅统计指定应用")
+	stats.Flags().String("sender", "", "仅统计指定发送人/标题")
+	stats.Flags().String("client", "", "按 clientLabel 过滤；all 为全部")
+	stats.Flags().String("dim", "all", "date|app|sender|hour|client|all")
+
+	storagePath := &cobra.Command{Use: "storage-path", Short: "打印 notifications 目录绝对路径", Args: cobra.NoArgs, RunE: run(notificationStoragePath)}
+
+	today := &cobra.Command{Use: "+today", Short: "今日通知摘要", Args: cobra.NoArgs, RunE: run(notificationToday)}
+	today.Flags().String("client", "", "按 clientLabel 过滤；all 为全部")
+	recent := &cobra.Command{Use: "+recent", Short: "最近 1 小时通知", Args: cobra.NoArgs, RunE: run(notificationRecent)}
+	recent.Flags().String("client", "", "按 clientLabel 过滤；all 为全部")
+	unread := &cobra.Command{Use: "+unread", Short: "（预留）未读通知", Args: cobra.NoArgs, RunE: run(notificationUnread)}
+
+	c.AddCommand(search, summary, stats, storagePath, today, recent, unread)
+	return c
+}
+
+func notificationSearch(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	opts, err := notif.BuildQueryOptions(rawQueryFromCmd(cmd), 100)
+	if err != nil {
+		return nil, err
+	}
+	return toAnySlice(notif.Query(ctx.Paths.Notifications, opts)), nil
+}
+
+func notificationSummary(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	sample := atoiDefault(flagStr(cmd, "sample"), 30)
+	top := atoiDefault(flagStr(cmd, "top"), 10)
+	raw := rawQueryFromCmd(cmd)
+	raw.Limit = ""
+	opts, err := notif.BuildQueryOptions(raw, maxLimit)
+	if err != nil {
+		return nil, err
+	}
+	items := notif.Query(ctx.Paths.Notifications, opts)
+	return map[string]any{
+		"ok":    true,
+		"total": len(items),
+		"range": map[string]any{"from": nilIfEmpty(raw.From), "to": nilIfEmpty(raw.To)},
+		"topApps": topCounts(items, func(n notif.StoredNotification) string {
+			return firstNonEmpty(n.AppDisplayName, n.AppName)
+		}, top),
+		"topSenders": topCounts(items, func(n notif.StoredNotification) string {
+			return firstNonEmpty(n.SenderName, n.Title)
+		}, top),
+		"sample": toAnySlice(sliceN(items, sample)),
+	}, nil
+}
+
+var dateOnlyRE = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`)
+var isoTimeRE = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$`)
+
+type statsBoundary struct {
+	raw        string
+	exactTs    *time.Time
+	startTs    time.Time
+	endTs      time.Time
+	minDateKey string
+	maxDateKey string
+}
+
+func parseStatsBoundary(value, optionName string) (statsBoundary, error) {
+	if dateOnlyRE.MatchString(value) {
+		t, err := time.ParseInLocation("2006-01-02", value, time.Local)
+		if err != nil {
+			return statsBoundary{}, errs.Newf(errs.CodeInvalidArgument, "%s 必须是合法日期 YYYY-MM-DD", optionName)
+		}
+		start := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, time.Local)
+		end := time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 999000000, time.Local)
+		return statsBoundary{raw: value, startTs: start, endTs: end, minDateKey: value, maxDateKey: value}, nil
+	}
+	if !isoTimeRE.MatchString(value) {
+		return statsBoundary{}, errs.Newf(errs.CodeInvalidArgument,
+			"%s 必须是 YYYY-MM-DD 或 ISO 8601 时间，例如 2026-06-02 或 2026-06-02T09:00:00+08:00", optionName)
+	}
+	exact, ok := notif.ParseTime(value)
+	if !ok {
+		return statsBoundary{}, errs.Newf(errs.CodeInvalidArgument, "%s 不是合法时间", optionName)
+	}
+	declaredKey := value[:10]
+	localKey := exact.In(time.Local).Format("2006-01-02")
+	lo, hi := declaredKey, localKey
+	if lo > hi {
+		lo, hi = hi, lo
+	}
+	e := exact
+	return statsBoundary{raw: value, exactTs: &e, startTs: exact, endTs: exact, minDateKey: lo, maxDateKey: hi}, nil
+}
+
+func notificationStats(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	fromRaw := flagStr(cmd, "from")
+	if fromRaw == "" {
+		fromRaw = localDaysAgo(7)
+	}
+	toRaw := flagStr(cmd, "to")
+	if toRaw == "" {
+		toRaw = localToday()
+	}
+	from, err := parseStatsBoundary(fromRaw, "--from")
+	if err != nil {
+		return nil, err
+	}
+	to, err := parseStatsBoundary(toRaw, "--to")
+	if err != nil {
+		return nil, err
+	}
+	if from.startTs.After(to.endTs) {
+		return nil, errs.New(errs.CodeInvalidArgument, "--from 不能晚于 --to")
+	}
+	dim := flagStr(cmd, "dim")
+	if dim == "" {
+		dim = "all"
+	}
+	allowed := map[string]bool{"date": true, "app": true, "sender": true, "hour": true, "client": true, "all": true}
+	if !allowed[dim] {
+		return nil, errs.New(errs.CodeInvalidArgument, "--dim 只能是 date|app|sender|hour|client|all")
+	}
+	opts := notif.QueryOptions{
+		App: flagStr(cmd, "app"), Sender: flagStr(cmd, "sender"), Client: flagStr(cmd, "client"),
+		Limit: maxLimit, FromTs: from.exactTs, ToTs: to.exactTs,
+		FromDateKey: from.minDateKey, ToDateKey: to.maxDateKey,
+	}
+	items := notif.Query(ctx.Paths.Notifications, opts)
+
+	dims := map[string]any{
+		"date":   topCounts(items, func(n notif.StoredNotification) string { return tsLocalDate(n.Timestamp) }, maxLimit),
+		"app":    topCounts(items, func(n notif.StoredNotification) string { return firstNonEmpty(n.AppDisplayName, n.AppName) }, maxLimit),
+		"sender": topCounts(items, func(n notif.StoredNotification) string { return firstNonEmpty(n.SenderName, n.Title) }, maxLimit),
+		"hour":   topCounts(items, func(n notif.StoredNotification) string { return tsLocalHour(n.Timestamp) }, maxLimit),
+		"client": topCounts(items, func(n notif.StoredNotification) string { return firstNonEmpty(n.ClientLabel, "legacy") }, maxLimit),
+	}
+	out := map[string]any{
+		"ok": true, "total": len(items),
+		"range": map[string]any{"from": from.raw, "to": to.raw}, "dim": dim,
+	}
+	if dim == "all" {
+		for k, v := range dims {
+			out[k] = v
+		}
+	} else {
+		out[dim] = dims[dim]
+	}
+	return out, nil
+}
+
+func notificationStoragePath(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return map[string]any{"ok": true, "path": ctx.Paths.Notifications}, nil
+}
+
+func notificationToday(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	day := localToday()
+	tz := localTZOffset()
+	raw := notif.RawQueryOpts{From: day + "T00:00:00" + tz, To: day + "T23:59:59" + tz, Client: flagStr(cmd, "client"), Limit: ""}
+	opts, err := notif.BuildQueryOptions(raw, maxLimit)
+	if err != nil {
+		return nil, err
+	}
+	return toAnySlice(notif.Query(ctx.Paths.Notifications, opts)), nil
+}
+
+func notificationRecent(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	fromTime := time.Now().Add(-time.Hour)
+	opts := notif.QueryOptions{
+		Limit: maxLimit, Client: flagStr(cmd, "client"), FromTs: &fromTime,
+		FromDateKey: fromTime.In(time.Local).Format("2006-01-02"),
+	}
+	return toAnySlice(notif.Query(ctx.Paths.Notifications, opts)), nil
+}
+
+func notificationUnread(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return nil, errs.New(errs.CodeNotImplemented, "+unread 预留：需要先落地通知的已读状态模型")
+}
+
+// ── helpers ──
+
+func topCounts(items []notif.StoredNotification, pick func(notif.StoredNotification) string, topN int) []any {
+	counts := map[string]int{}
+	for _, item := range items {
+		if k := pick(item); k != "" {
+			counts[k]++
+		}
+	}
+	type kc struct {
+		key   string
+		count int
+	}
+	rows := make([]kc, 0, len(counts))
+	for k, v := range counts {
+		rows = append(rows, kc{k, v})
+	}
+	sort.Slice(rows, func(i, j int) bool {
+		if rows[i].count != rows[j].count {
+			return rows[i].count > rows[j].count
+		}
+		return rows[i].key < rows[j].key
+	})
+	if topN < len(rows) {
+		rows = rows[:topN]
+	}
+	out := make([]any, 0, len(rows))
+	for _, r := range rows {
+		out = append(out, map[string]any{"key": r.key, "count": r.count})
+	}
+	return out
+}
+
+func toAnySlice(items []notif.StoredNotification) []any {
+	out := make([]any, 0, len(items))
+	for _, it := range items {
+		out = append(out, it)
+	}
+	return out
+}
+
+func sliceN(items []notif.StoredNotification, n int) []notif.StoredNotification {
+	if n < len(items) {
+		return items[:n]
+	}
+	return items
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func nilIfEmpty(s string) any {
+	if s == "" {
+		return nil
+	}
+	return s
+}
+
+func atoiDefault(s string, def int) int {
+	if s == "" {
+		return def
+	}
+	var n int
+	if _, err := fmt.Sscanf(s, "%d", &n); err != nil {
+		return def
+	}
+	return n
+}
+
+func localToday() string        { return time.Now().Format("2006-01-02") }
+func localDaysAgo(n int) string { return time.Now().AddDate(0, 0, -n).Format("2006-01-02") }
+func tsLocalDate(ts string) string {
+	t, ok := notif.ParseTime(ts)
+	if !ok {
+		return ""
+	}
+	return t.In(time.Local).Format("2006-01-02")
+}
+func tsLocalHour(ts string) string {
+	t, ok := notif.ParseTime(ts)
+	if !ok {
+		return ""
+	}
+	return t.In(time.Local).Format("15")
+}
+
+func localTZOffset() string {
+	_, offset := time.Now().Zone()
+	sign := "+"
+	if offset < 0 {
+		sign = "-"
+		offset = -offset
+	}
+	hh := offset / 3600
+	mm := (offset % 3600) / 60
+	return fmt.Sprintf("%s%02d:%02d", sign, hh, mm)
+}
diff --git a/internal/cli/cmd_profile.go b/internal/cli/cmd_profile.go
new file mode 100644
index 0000000..ffbb083
--- /dev/null
+++ b/internal/cli/cmd_profile.go
@@ -0,0 +1,120 @@
+package cli
+
+import (
+	"os"
+	"sort"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/paths"
+	"github.com/YoooClaw/cli/internal/prompt"
+	"github.com/spf13/cobra"
+)
+
+func newProfileCmd() *cobra.Command {
+	c := &cobra.Command{Use: "profile", Short: "多 profile 管理 🟢"}
+
+	listCmd := &cobra.Command{Use: "list", Short: "列出所有 profile，标注 active", Args: cobra.NoArgs, RunE: run(profileList)}
+	useCmd := &cobra.Command{Use: "use <name>", Short: "切换 active profile", Args: cobra.ExactArgs(1), RunE: run(profileUse)}
+	createCmd := &cobra.Command{Use: "create <name>", Short: "新建 profile（走 config init 向导）", Args: cobra.ExactArgs(1), RunE: run(profileCreate)}
+	createCmd.Flags().Bool("non-interactive", false, "跳过向导（配合 --from-file）")
+	createCmd.Flags().String("from-file", "", "从 JSON 文件导入配置（- 为 stdin）")
+	createCmd.Flags().Bool("force", false, "已存在 config 时覆盖")
+	createCmd.Flags().Bool("no-start", false, "只生成配置，不自动启动 daemon")
+	deleteCmd := &cobra.Command{Use: "delete <name>", Short: "删除 profile（非 active，需 --yes）", Args: cobra.ExactArgs(1), RunE: run(profileDelete)}
+	deleteCmd.Flags().Bool("yes", false, "跳过确认")
+
+	c.AddCommand(listCmd, useCmd, createCmd, deleteCmd)
+	return c
+}
+
+func profileList(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	active := paths.ReadActiveProfile()
+	if active == "" {
+		active = paths.DefaultProfile
+	}
+	names := paths.ListProfileNames()
+	for _, implied := range []string{active, paths.DefaultProfile} {
+		if !contains(names, implied) {
+			names = append(names, implied)
+		}
+	}
+	sort.Strings(names)
+	out := make([]any, 0, len(names))
+	for _, name := range names {
+		out = append(out, map[string]any{
+			"name":        name,
+			"active":      name == active,
+			"initialized": config.Exists(paths.For(name)),
+		})
+	}
+	return out, nil
+}
+
+func profileUse(_ *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	name := args[0]
+	p := paths.For(name)
+	if !fsutil.Exists(p.Dir) {
+		return nil, errs.New(errs.CodeProfileNotFound, "profile `"+name+"` 不存在",
+			map[string]any{"hint": "用 yoooclaw profile create 新建", "checkedPaths": []string{p.Dir}})
+	}
+	if err := fsutil.WriteAtomic(paths.ActiveProfilePath(), []byte(name+"\n"), fsutil.ConfigFileMode); err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": true, "active": name}, nil
+}
+
+func profileCreate(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	name := args[0]
+	p := paths.For(name)
+	if config.Exists(p) {
+		return nil, errs.New(errs.CodeAlreadyExists, "profile `"+name+"` 已存在")
+	}
+	subCtx := &clictx.Context{Profile: name, Paths: p, Format: ctx.Format, Quiet: ctx.Quiet, Color: ctx.Color}
+	return initCore(subCtx, initOpts{
+		force:          flagBool(cmd, "force"),
+		nonInteractive: flagBool(cmd, "non-interactive"),
+		fromFile:       flagStr(cmd, "from-file"),
+		noStart:        flagBool(cmd, "no-start"),
+	})
+}
+
+func profileDelete(_ *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	name := args[0]
+	active := paths.ReadActiveProfile()
+	if active == "" {
+		active = paths.DefaultProfile
+	}
+	if name == active {
+		return nil, errs.New(errs.CodeInvalidArgument, "不能删除当前 active profile `"+name+"`",
+			map[string]any{"hint": "先 yoooclaw profile use <其他 profile> 再删除"})
+	}
+	p := paths.For(name)
+	if !fsutil.Exists(p.Dir) {
+		return nil, errs.New(errs.CodeProfileNotFound, "profile `"+name+"` 不存在")
+	}
+	if !flagBool(cmd, "yes") {
+		ok, err := prompt.Confirm("确认删除 profile `"+name+"` 及其全部数据？", false)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			return nil, errs.New(errs.CodeConfirmationRequired, "已取消")
+		}
+	}
+	if err := os.RemoveAll(p.Dir); err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": true, "deleted": name}, nil
+}
+
+func contains(s []string, v string) bool {
+	for _, x := range s {
+		if x == v {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/cli/handler.go b/internal/cli/handler.go
new file mode 100644
index 0000000..e442e4f
--- /dev/null
+++ b/internal/cli/handler.go
@@ -0,0 +1,76 @@
+package cli
+
+import (
+	"os"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+// exitCode 记录命令执行后的进程退出码（错误时由 wrapper 设置），由 Execute 读取。
+var exitCode int
+
+// handler 是命令实现签名：拿到上下文 + cobra 命令/位置参数，返回可序列化结果或错误。
+type handler func(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error)
+
+// flagStr 读取（含继承的全局）字符串 flag。
+func flagStr(cmd *cobra.Command, name string) string {
+	v, _ := cmd.Flags().GetString(name)
+	return v
+}
+
+// flagBool 读取（含继承的全局）布尔 flag；flag 不存在返回 false。
+func flagBool(cmd *cobra.Command, name string) bool {
+	if cmd.Flags().Lookup(name) == nil {
+		return false
+	}
+	v, _ := cmd.Flags().GetBool(name)
+	return v
+}
+
+// buildContext 从命令的全局 flags 物化 CliContext。
+func buildContext(cmd *cobra.Command) (*clictx.Context, error) {
+	color := true
+	if cmd.Flags().Lookup("no-color") != nil {
+		noColor, _ := cmd.Flags().GetBool("no-color")
+		color = !noColor
+	}
+	return clictx.Build(flagStr(cmd, "profile"), flagStr(cmd, "format"), flagBool(cmd, "quiet"), color)
+}
+
+// run 把 handler 包成 cobra RunE：构建 ctx → 执行 → 统一渲染结果/错误并设置退出码。
+// 本地 --json flag 作为全局 --format json 的兼容别名（doctor / update self 用）。
+func run(h handler) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		ctx, err := buildContext(cmd)
+		format := output.JSON
+		if ctx != nil {
+			format = ctx.Format
+		}
+		if flagBool(cmd, "json") {
+			format = output.JSON
+		}
+		if err != nil {
+			output.RenderError(os.Stdout, err, format)
+			exitCode = 1
+			return nil
+		}
+		result, herr := h(ctx, cmd, args)
+		if herr != nil {
+			output.RenderError(os.Stdout, herr, format)
+			exitCode = exitCodeOf(herr)
+			return nil
+		}
+		output.RenderResult(os.Stdout, result, format)
+		return nil
+	}
+}
+
+func exitCodeOf(err error) int {
+	if e, ok := err.(*errs.Error); ok && e.ExitCode != 0 {
+		return e.ExitCode
+	}
+	return 1
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
new file mode 100644
index 0000000..5920843
--- /dev/null
+++ b/internal/cli/root.go
@@ -0,0 +1,46 @@
+// Package cli 装配 yoooclaw CLI 的命令树（cobra），对齐 TS 版 command-tree + program.ts。
+package cli
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/YoooClaw/cli/internal/version"
+	"github.com/spf13/cobra"
+)
+
+func newRootCmd() *cobra.Command {
+	root := &cobra.Command{
+		Use:           "yoooclaw",
+		Short:         "yoooclaw CLI",
+		Long:          "yoooclaw —— 独立守护进程 + CLI：接收手机通知、Relay 隧道、灯效规则评估（Agent-Native）。",
+		Version:       version.Version,
+		SilenceUsage:  true,
+		SilenceErrors: true,
+	}
+	root.SetVersionTemplate("{{.Version}}\n")
+
+	// 全局 flags（对所有命令生效）。
+	root.PersistentFlags().String("profile", "", "切换 profile（默认 default）")
+	root.PersistentFlags().String("format", "", "输出格式：json|pretty|table|ndjson（TTY 默认 pretty，管道默认 json）")
+	root.PersistentFlags().Bool("quiet", false, "抑制进度日志，只输出最终结果")
+	root.PersistentFlags().Bool("no-color", false, "关闭终端颜色")
+
+	root.AddCommand(
+		newConfigCmd(),
+		newProfileCmd(),
+		newAuthCmd(),
+		newNotificationCmd(),
+		newDoctorCmd(),
+	)
+	return root
+}
+
+// Execute 构建 root 命令并运行。
+func Execute() {
+	if err := newRootCmd().Execute(); err != nil {
+		fmt.Fprintln(os.Stderr, "error:", err)
+		os.Exit(1)
+	}
+	os.Exit(exitCode)
+}
diff --git a/internal/clictx/clictx.go b/internal/clictx/clictx.go
new file mode 100644
index 0000000..3c3413a
--- /dev/null
+++ b/internal/clictx/clictx.go
@@ -0,0 +1,50 @@
+// Package clictx 把全局 flags 物化成贯穿命令的执行上下文（对齐 TS 版 src/context.ts）。
+package clictx
+
+import (
+	"os"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/output"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// Context 是贯穿所有命令的执行上下文。
+type Context struct {
+	Profile string
+	Paths   paths.Paths
+	Format  output.Format
+	Quiet   bool
+	Color   bool
+}
+
+// ResolveActiveProfile 解析当前 active profile：
+// --profile > $YOOOCLAW_PROFILE > active-profile 文件 > default。
+func ResolveActiveProfile(flagProfile string) string {
+	if s := strings.TrimSpace(flagProfile); s != "" {
+		return s
+	}
+	if s := strings.TrimSpace(os.Getenv("YOOOCLAW_PROFILE")); s != "" {
+		return s
+	}
+	if s := paths.ReadActiveProfile(); s != "" {
+		return s
+	}
+	return paths.DefaultProfile
+}
+
+// Build 构造 CliContext。
+func Build(flagProfile, format string, quiet, color bool) (*Context, error) {
+	profile := ResolveActiveProfile(flagProfile)
+	fmtResolved, err := output.ResolveFormat(format, output.StdoutIsTTY())
+	if err != nil {
+		return nil, err
+	}
+	return &Context{
+		Profile: profile,
+		Paths:   paths.For(profile),
+		Format:  fmtResolved,
+		Quiet:   quiet,
+		Color:   color,
+	}, nil
+}
diff --git a/internal/config/config.go b/internal/config/config.go
new file mode 100644
index 0000000..dc1bb48
--- /dev/null
+++ b/internal/config/config.go
@@ -0,0 +1,180 @@
+// Package config 定义 daemon 配置 schema 并提供读写 + 点号路径 get/set/unset + 遮罩
+// （对齐 TS 版 src/config/schema.ts 与 src/config/store.ts）。
+//
+// 敏感字段（gateway token / webhook secret）不直接落这里，而用 *Ref 抽象引用指向
+// credentials 文件 / keychain / env。
+package config
+
+import (
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// ConfigVersion 是当前 config.json schema 版本。
+const ConfigVersion = 1
+
+// 默认值常量。
+const (
+	DefaultPort         = 18789
+	DefaultBind         = "127.0.0.1"
+	DefaultImageMaxByte = 20 * 1024 * 1024
+)
+
+// RelayHost 是默认 Relay 主机；可由构建期 ldflags 注入覆盖，未注入时回退生产域名。
+var RelayHost = "openclaw-service.yoooclaw.com"
+
+// DefaultRelayURL 返回默认 Relay 隧道地址（复用 phone-notifications 托管 Relay）。
+func DefaultRelayURL() string {
+	return "wss://" + RelayHost + "/message/messages/ws/plugin"
+}
+
+// SecretRefPaths 是 config.json 里需要遮罩展示的敏感引用字段（点号路径）。
+var SecretRefPaths = []string{
+	"auth.tokenRef",
+	"lightRules.evaluator.webhookSecretRef",
+}
+
+// DaemonSection 守护进程监听配置。
+type DaemonSection struct {
+	Bind     string `json:"bind"`
+	Port     int    `json:"port"`
+	LogLevel string `json:"logLevel"`
+	Detach   bool   `json:"detach"`
+}
+
+// AuthSection 鉴权配置。
+type AuthSection struct {
+	Mode     string `json:"mode"`
+	TokenRef string `json:"tokenRef"`
+}
+
+// RelaySection Relay 隧道配置。
+type RelaySection struct {
+	URL                string `json:"url"`
+	HeartbeatSec       int    `json:"heartbeatSec"`
+	ReconnectBackoffMs int    `json:"reconnectBackoffMs"`
+	Enabled            bool   `json:"enabled"`
+}
+
+// NotificationSection 通知存储配置。RetentionDays 为 nil 表示永久保存。
+type NotificationSection struct {
+	RetentionDays *int     `json:"retentionDays"`
+	IgnoredApps   []string `json:"ignoredApps"`
+}
+
+// WebhookEvaluatorSection 灯效 webhook 评估器配置。
+type WebhookEvaluatorSection struct {
+	Mode             string `json:"mode"`
+	WebhookURL       string `json:"webhookUrl"`
+	WebhookSecretRef string `json:"webhookSecretRef"`
+	TimeoutMs        int    `json:"timeoutMs"`
+	Retries          int    `json:"retries"`
+}
+
+// LightRulesSection 灯效规则配置。
+type LightRulesSection struct {
+	Enabled   bool                     `json:"enabled"`
+	Evaluator *WebhookEvaluatorSection `json:"evaluator,omitempty"`
+}
+
+// AutoUpdateSection 自动更新配置。
+type AutoUpdateSection struct {
+	Enabled bool   `json:"enabled"`
+	Channel string `json:"channel"`
+}
+
+// OutputSection 输出默认格式配置。
+type OutputSection struct {
+	DefaultFormat string `json:"defaultFormat"`
+}
+
+// ImageSection 图片下载配置。
+type ImageSection struct {
+	MaxBytes int64 `json:"maxBytes"`
+}
+
+// Config 是 per-profile config.json 的完整结构。
+type Config struct {
+	Version      int                 `json:"version"`
+	Daemon       DaemonSection       `json:"daemon"`
+	Auth         AuthSection         `json:"auth"`
+	Relay        RelaySection        `json:"relay"`
+	Notification NotificationSection `json:"notification"`
+	LightRules   LightRulesSection   `json:"lightRules"`
+	AutoUpdate   AutoUpdateSection   `json:"autoUpdate"`
+	Output       OutputSection       `json:"output"`
+	Image        ImageSection        `json:"image"`
+}
+
+// Default 生成某个 profile 的默认 config。tokenRef/secretRef 指向该 profile 的 credentials 文件。
+func Default(credentialsPath string) Config {
+	return Config{
+		Version: ConfigVersion,
+		Daemon: DaemonSection{
+			Bind:     DefaultBind,
+			Port:     DefaultPort,
+			LogLevel: "info",
+			Detach:   true,
+		},
+		Auth: AuthSection{
+			Mode:     "token",
+			TokenRef: "file:" + credentialsPath + "#gatewayToken",
+		},
+		Relay: RelaySection{
+			URL:                DefaultRelayURL(),
+			HeartbeatSec:       10,
+			ReconnectBackoffMs: 2000,
+			Enabled:            true,
+		},
+		Notification: NotificationSection{
+			RetentionDays: nil,
+			IgnoredApps:   []string{},
+		},
+		LightRules: LightRulesSection{Enabled: true},
+		AutoUpdate: AutoUpdateSection{Enabled: true, Channel: "stable"},
+		Output:     OutputSection{DefaultFormat: "auto"},
+		Image:      ImageSection{MaxBytes: DefaultImageMaxByte},
+	}
+}
+
+// DefaultEvaluator 返回默认 webhook 评估器（config init 启用灯效评估时填充）。
+func DefaultEvaluator(credentialsPath string) WebhookEvaluatorSection {
+	return WebhookEvaluatorSection{
+		Mode:             "webhook",
+		WebhookURL:       "",
+		WebhookSecretRef: "file:" + credentialsPath + "#evaluatorSecret",
+		TimeoutMs:        5000,
+		Retries:          1,
+	}
+}
+
+// Exists 报告 config.json 是否已存在。
+func Exists(p paths.Paths) bool {
+	return fsutil.Exists(p.Config)
+}
+
+// Load 读取 config；缺失字段用默认值补齐（Go json.Unmarshal 覆盖默认结构体 = deepMerge 语义）。
+// 文件不存在则返回纯默认。
+func Load(p paths.Paths) (Config, error) {
+	cfg := Default(p.Credentials)
+	if _, err := fsutil.ReadJSON(p.Config, &cfg); err != nil {
+		return cfg, err
+	}
+	return cfg, nil
+}
+
+// Require 要求 config 必须已存在（如 daemon 启动），否则报错。
+func Require(p paths.Paths) (Config, error) {
+	if !Exists(p) {
+		return Config{}, errs.New(errs.CodeConfigInvalid,
+			"profile `"+p.Profile+"` 尚未初始化",
+			map[string]any{"hint": "先运行 yoooclaw config init", "checkedPaths": []string{p.Config}})
+	}
+	return Load(p)
+}
+
+// Save 写 config.json（0644）。
+func Save(p paths.Paths, cfg Config) error {
+	return fsutil.WriteJSON(p.Config, cfg, fsutil.ConfigFileMode)
+}
diff --git a/internal/config/dotpath.go b/internal/config/dotpath.go
new file mode 100644
index 0000000..1ecf9cb
--- /dev/null
+++ b/internal/config/dotpath.go
@@ -0,0 +1,182 @@
+package config
+
+import (
+	"encoding/json"
+	"strconv"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// LoadRaw 读取 config.json 为通用 map（用于 set/unset/show 的点号路径操作）。
+// 文件不存在则返回默认 config 序列化后的 map。
+func LoadRaw(p paths.Paths) (map[string]any, error) {
+	var m map[string]any
+	exists, err := fsutil.ReadJSON(p.Config, &m)
+	if err != nil {
+		return nil, err
+	}
+	if !exists {
+		return toMap(Default(p.Credentials)), nil
+	}
+	return m, nil
+}
+
+// SaveRaw 把通用 map 写回 config.json。
+func SaveRaw(p paths.Paths, m map[string]any) error {
+	return fsutil.WriteJSON(p.Config, m, fsutil.ConfigFileMode)
+}
+
+// LoadMergedMap 加载「默认 + 存储」深合并后的完整 config，并转成 map（供 set/unset 写回全量）。
+func LoadMergedMap(p paths.Paths) (map[string]any, error) {
+	cfg, err := Load(p)
+	if err != nil {
+		return nil, err
+	}
+	return toMap(cfg), nil
+}
+
+// ToMap 把 Config 转成与磁盘一致的 map 形态。
+func ToMap(cfg Config) map[string]any {
+	return toMap(cfg)
+}
+
+func toMap(cfg Config) map[string]any {
+	// 经 JSON 往返得到与磁盘一致的 map 形态。
+	out := map[string]any{}
+	b, _ := json.Marshal(cfg)
+	_ = json.Unmarshal(b, &out)
+	return out
+}
+
+// GetByPath 按点号路径取值。
+func GetByPath(obj any, path string) (any, bool) {
+	cursor := obj
+	for _, seg := range strings.Split(path, ".") {
+		m, ok := cursor.(map[string]any)
+		if !ok {
+			return nil, false
+		}
+		cursor, ok = m[seg]
+		if !ok {
+			return nil, false
+		}
+	}
+	return cursor, true
+}
+
+// SetByPath 按点号路径设值（中间缺失对象自动创建）。
+func SetByPath(obj map[string]any, path string, value any) {
+	segs := strings.Split(path, ".")
+	cursor := obj
+	for i := 0; i < len(segs)-1; i++ {
+		next, ok := cursor[segs[i]].(map[string]any)
+		if !ok {
+			next = map[string]any{}
+			cursor[segs[i]] = next
+		}
+		cursor = next
+	}
+	cursor[segs[len(segs)-1]] = value
+}
+
+// UnsetByPath 按点号路径删除；返回是否删除了字段。
+func UnsetByPath(obj map[string]any, path string) bool {
+	segs := strings.Split(path, ".")
+	cursor := obj
+	for i := 0; i < len(segs)-1; i++ {
+		next, ok := cursor[segs[i]].(map[string]any)
+		if !ok {
+			return false
+		}
+		cursor = next
+	}
+	last := segs[len(segs)-1]
+	if _, ok := cursor[last]; !ok {
+		return false
+	}
+	delete(cursor, last)
+	return true
+}
+
+var numberPaths = map[string]bool{
+	"daemon.port":                    true,
+	"relay.heartbeatSec":             true,
+	"relay.reconnectBackoffMs":       true,
+	"notification.retentionDays":     true,
+	"lightRules.evaluator.timeoutMs": true,
+	"lightRules.evaluator.retries":   true,
+	"image.maxBytes":                 true,
+}
+
+var booleanPaths = map[string]bool{
+	"daemon.detach":      true,
+	"relay.enabled":      true,
+	"lightRules.enabled": true,
+	"autoUpdate.enabled": true,
+}
+
+var arrayPaths = map[string]bool{
+	"notification.ignoredApps": true,
+}
+
+// CoerceValue 把命令行字符串值按目标字段类型强转。
+func CoerceValue(path, raw string) (any, error) {
+	switch {
+	case numberPaths[path]:
+		if path == "notification.retentionDays" && (raw == "null" || raw == "") {
+			return nil, nil
+		}
+		n, err := strconv.ParseFloat(raw, 64)
+		if err != nil {
+			return nil, errs.Newf(errs.CodeInvalidArgument, "%s 需要数字，收到：%s", path, raw)
+		}
+		return n, nil
+	case booleanPaths[path]:
+		switch raw {
+		case "true":
+			return true, nil
+		case "false":
+			return false, nil
+		}
+		return nil, errs.Newf(errs.CodeInvalidArgument, "%s 需要 true/false，收到：%s", path, raw)
+	case arrayPaths[path]:
+		parts := strings.Split(raw, ",")
+		out := make([]any, 0, len(parts))
+		for _, s := range parts {
+			if t := strings.TrimSpace(s); t != "" {
+				out = append(out, t)
+			}
+		}
+		return out, nil
+	default:
+		return raw, nil
+	}
+}
+
+// Mask 深拷贝并遮罩敏感字段，供 config show 用。inline: 引用整体遮罩。
+func Mask(m map[string]any) map[string]any {
+	clone := deepCloneMap(m)
+	for _, path := range SecretRefPaths {
+		if v, ok := GetByPath(clone, path); ok {
+			if s, ok := v.(string); ok && strings.HasPrefix(s, "inline:") {
+				SetByPath(clone, path, "inline:****")
+			}
+		}
+	}
+	return clone
+}
+
+func deepCloneMap(m map[string]any) map[string]any {
+	out := map[string]any{}
+	for k, v := range m {
+		if sub, ok := v.(map[string]any); ok {
+			out[k] = deepCloneMap(sub)
+		} else {
+			out[k] = v
+		}
+	}
+	return out
+}
diff --git a/internal/creds/refs.go b/internal/creds/refs.go
new file mode 100644
index 0000000..e650fdd
--- /dev/null
+++ b/internal/creds/refs.go
@@ -0,0 +1,140 @@
+// Package creds 提供凭据抽象引用（*Ref）解析与写入，以及 api-key 分层解析。
+//
+// 支持 scheme：
+//   - env:<VAR>                  从环境变量读（最高优先级覆盖）
+//   - file:<path>#<jsonField>    从 JSON 文件某字段读/写（默认落点，0600）
+//   - keychain:<service>/<acct>  从 OS keychain 读/写（可选加固）
+//   - inline:<base64>            直接内嵌
+package creds
+
+import (
+	"encoding/base64"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/keychain"
+)
+
+// ResolvedRef 是 ref 解析结果。
+type ResolvedRef struct {
+	Value    string
+	Source   string // env | file | keychain | inline
+	Location string
+}
+
+func expandHome(path string) string {
+	if path == "~" {
+		h, _ := os.UserHomeDir()
+		return h
+	}
+	if strings.HasPrefix(path, "~/") {
+		h, _ := os.UserHomeDir()
+		return filepath.Join(h, path[2:])
+	}
+	return path
+}
+
+func parseFileRef(rest string) (path, field string, err error) {
+	hashIdx := strings.LastIndex(rest, "#")
+	if hashIdx < 0 {
+		return "", "", errs.New(errs.CodeConfigInvalid, "file: 引用缺少 #字段："+rest).
+			WithHint("格式应为 file:<path>#<jsonField>")
+	}
+	return expandHome(rest[:hashIdx]), rest[hashIdx+1:], nil
+}
+
+func parseKeychainRef(rest string) (service, account string, err error) {
+	slashIdx := strings.Index(rest, "/")
+	if slashIdx < 0 {
+		return "", "", errs.New(errs.CodeConfigInvalid, "keychain: 引用缺少 /account："+rest).
+			WithHint("格式应为 keychain:<service>/<account>")
+	}
+	return rest[:slashIdx], rest[slashIdx+1:], nil
+}
+
+// ResolveRef 解析一个 ref，返回当前值（可能为空）与来源。
+func ResolveRef(ref string) (ResolvedRef, error) {
+	colonIdx := strings.Index(ref, ":")
+	if colonIdx < 0 {
+		return ResolvedRef{}, errs.New(errs.CodeConfigInvalid, "非法凭据引用："+ref).
+			WithHint("支持 env: / file: / keychain: / inline:")
+	}
+	scheme, rest := ref[:colonIdx], ref[colonIdx+1:]
+
+	switch scheme {
+	case "env":
+		return ResolvedRef{Source: "env", Value: strings.TrimSpace(os.Getenv(rest)), Location: rest}, nil
+	case "file":
+		path, field, err := parseFileRef(rest)
+		if err != nil {
+			return ResolvedRef{}, err
+		}
+		var data map[string]any
+		if _, err := fsutil.ReadJSON(path, &data); err != nil {
+			return ResolvedRef{}, err
+		}
+		val, _ := data[field].(string)
+		return ResolvedRef{Source: "file", Value: val, Location: path}, nil
+	case "keychain":
+		service, account, err := parseKeychainRef(rest)
+		if err != nil {
+			return ResolvedRef{}, err
+		}
+		r := keychain.Get(service, account)
+		return ResolvedRef{Source: "keychain", Value: r.Value, Location: service + "/" + account}, nil
+	case "inline":
+		decoded, _ := base64.StdEncoding.DecodeString(rest)
+		return ResolvedRef{Source: "inline", Value: string(decoded)}, nil
+	default:
+		return ResolvedRef{}, errs.New(errs.CodeConfigInvalid, "不支持的凭据引用 scheme："+scheme).
+			WithHint("支持 env: / file: / keychain: / inline:")
+	}
+}
+
+// WriteRef 把值写入 ref 指向的后端。env/inline 不可持久写入（报错）。
+func WriteRef(ref, value string) (ResolvedRef, error) {
+	colonIdx := strings.Index(ref, ":")
+	if colonIdx < 0 {
+		return ResolvedRef{}, errs.New(errs.CodeConfigInvalid, "非法凭据引用："+ref)
+	}
+	scheme, rest := ref[:colonIdx], ref[colonIdx+1:]
+
+	switch scheme {
+	case "file":
+		path, field, err := parseFileRef(rest)
+		if err != nil {
+			return ResolvedRef{}, err
+		}
+		data := map[string]any{}
+		if _, err := fsutil.ReadJSON(path, &data); err != nil {
+			return ResolvedRef{}, err
+		}
+		if data == nil {
+			data = map[string]any{}
+		}
+		data[field] = value
+		if err := fsutil.WriteJSON(path, data, fsutil.SecretFileMode); err != nil {
+			return ResolvedRef{}, err
+		}
+		return ResolvedRef{Source: "file", Value: value, Location: path}, nil
+	case "keychain":
+		service, account, err := parseKeychainRef(rest)
+		if err != nil {
+			return ResolvedRef{}, err
+		}
+		if !keychain.Set(service, account, value) {
+			return ResolvedRef{}, errs.New(errs.CodeKeychainUnavailable, "keychain 写入失败："+service+"/"+account).
+				WithHint("当前平台可能没有可用的 keychain 工具，请改用 file: 引用")
+		}
+		return ResolvedRef{Source: "keychain", Value: value, Location: service + "/" + account}, nil
+	case "env":
+		return ResolvedRef{}, errs.New(errs.CodeInvalidArgument, "env: 引用无法持久化写入；请改用 file: 或 keychain:")
+	case "inline":
+		return ResolvedRef{}, errs.New(errs.CodeInvalidArgument, "inline: 引用需直接写进 config，不通过 writeRef")
+	default:
+		return ResolvedRef{}, errs.New(errs.CodeConfigInvalid, "不支持的凭据引用 scheme："+scheme)
+	}
+}
diff --git a/internal/creds/store.go b/internal/creds/store.go
new file mode 100644
index 0000000..13d4e14
--- /dev/null
+++ b/internal/creds/store.go
@@ -0,0 +1,478 @@
+package creds
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"os"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/keychain"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+const (
+	APIKeyEnv             = "YOOOCLAW_API_KEY"
+	KeychainService       = "yoooclaw"
+	KeychainAPIKeyAccount = "api-key"
+	apiKeyField           = "apiKey"
+	apiKeysField          = "apiKeys"
+)
+
+var (
+	reservedLabels = map[string]bool{"all": true, "legacy": true, "env": true, "keychain": true, "local": true}
+	labelRE        = regexp.MustCompile(`^[a-z0-9-]{1,32}$`)
+)
+
+// ApiKeyEntry 是运行时 api-key 条目。
+type ApiKeyEntry struct {
+	Label     string
+	Key       string
+	Default   bool
+	Source    string // env | keychain | file
+	CreatedAt string
+}
+
+// ApiKeyResolution 是单个 api-key 解析结果。
+type ApiKeyResolution struct {
+	Value    string
+	Source   string // env | keychain | file | none
+	Location string
+	Label    string
+}
+
+// CredentialSet 是 account 级 api-key 的整体解析结果。
+type CredentialSet struct {
+	Mode                    string
+	Entries                 []ApiKeyEntry
+	DefaultEntry            *ApiKeyEntry
+	Location                string
+	LegacyAPIKeyPresent     bool
+	ShadowedKeychainPresent bool
+	Warnings                []string
+}
+
+type storedEntry struct {
+	Label     string
+	Key       string
+	Default   bool
+	CreatedAt string
+}
+
+// IsValidAPIKeyLabel 校验 label 合法性。
+func IsValidAPIKeyLabel(label string) bool {
+	return labelRE.MatchString(label) && !reservedLabels[label]
+}
+
+// AssertValidAPIKeyLabel 校验失败时返回错误。
+func AssertValidAPIKeyLabel(label string) error {
+	if !IsValidAPIKeyLabel(label) {
+		return errs.New(errs.CodeAPIKeyLabelInvalid,
+			"label 不合法：仅允许 [a-z0-9-]{1,32}，且不能使用保留字 all/legacy/env/keychain/local",
+			map[string]any{"label": label})
+	}
+	return nil
+}
+
+func readSharedCredentials() map[string]any {
+	data := map[string]any{}
+	_, _ = fsutil.ReadJSON(paths.SharedCredentialsPath(), &data)
+	if data == nil {
+		data = map[string]any{}
+	}
+	return data
+}
+
+func writeSharedCredentials(data map[string]any) error {
+	return fsutil.WriteJSON(paths.SharedCredentialsPath(), data, fsutil.SecretFileMode)
+}
+
+func normalizeStoredEntries(raw any, warnings *[]string) []storedEntry {
+	arr, ok := raw.([]any)
+	if !ok {
+		return nil
+	}
+	seen := map[string]bool{}
+	var out []storedEntry
+	for _, item := range arr {
+		obj, ok := item.(map[string]any)
+		if !ok {
+			*warnings = append(*warnings, "apiKeys[] 包含非对象条目，已跳过")
+			continue
+		}
+		label, _ := obj["label"].(string)
+		label = strings.TrimSpace(label)
+		key, _ := obj["key"].(string)
+		key = strings.TrimSpace(key)
+		if !IsValidAPIKeyLabel(label) {
+			disp := label
+			if disp == "" {
+				disp = "<empty>"
+			}
+			*warnings = append(*warnings, "apiKeys[] 包含非法 label: "+disp+"，已跳过")
+			continue
+		}
+		if key == "" {
+			*warnings = append(*warnings, "apiKeys[] label="+label+" 的 key 为空，已跳过")
+			continue
+		}
+		if seen[label] {
+			*warnings = append(*warnings, "apiKeys[] label="+label+" 重复，已跳过后续条目")
+			continue
+		}
+		seen[label] = true
+		createdAt, _ := obj["createdAt"].(string)
+		out = append(out, storedEntry{
+			Label:     label,
+			Key:       key,
+			Default:   obj["default"] == true,
+			CreatedAt: createdAt,
+		})
+	}
+	return out
+}
+
+func toRuntimeEntries(entries []storedEntry) []ApiKeyEntry {
+	defaultIdx := -1
+	for i, e := range entries {
+		if e.Default {
+			defaultIdx = i
+			break
+		}
+	}
+	effective := -1
+	if len(entries) > 0 {
+		if defaultIdx >= 0 {
+			effective = defaultIdx
+		} else {
+			effective = 0
+		}
+	}
+	out := make([]ApiKeyEntry, len(entries))
+	for i, e := range entries {
+		out[i] = ApiKeyEntry{Label: e.Label, Key: e.Key, Default: i == effective, Source: "file", CreatedAt: e.CreatedAt}
+	}
+	return out
+}
+
+func pickDefault(entries []ApiKeyEntry) *ApiKeyEntry {
+	for i := range entries {
+		if entries[i].Default {
+			return &entries[i]
+		}
+	}
+	if len(entries) > 0 {
+		return &entries[0]
+	}
+	return nil
+}
+
+func keychainValue() string {
+	if !keychain.Available() {
+		return ""
+	}
+	return keychain.Get(KeychainService, KeychainAPIKeyAccount).Value
+}
+
+func storedEntriesFromFile(data map[string]any) []storedEntry {
+	var warnings []string
+	return normalizeStoredEntries(data[apiKeysField], &warnings)
+}
+
+func writeAPIKeys(entries []storedEntry) (ApiKeyResolution, error) {
+	data := readSharedCredentials()
+	arr := make([]any, 0, len(entries))
+	for _, e := range entries {
+		obj := map[string]any{"label": e.Label, "key": e.Key}
+		if e.Default {
+			obj["default"] = true
+		}
+		if e.CreatedAt != "" {
+			obj["createdAt"] = e.CreatedAt
+		}
+		arr = append(arr, obj)
+	}
+	data[apiKeysField] = arr
+	delete(data, apiKeyField)
+	if err := writeSharedCredentials(data); err != nil {
+		return ApiKeyResolution{}, err
+	}
+	runtime := toRuntimeEntries(entries)
+	chosen := pickDefault(runtime)
+	res := ApiKeyResolution{Source: "none", Location: paths.SharedCredentialsPath()}
+	if chosen != nil {
+		res.Value, res.Source, res.Label = chosen.Key, chosen.Source, chosen.Label
+	}
+	return res, nil
+}
+
+// ResolveAPIKeyEntries 分层解析 account 级 api-key（env > keychain > file），命中即停。
+func ResolveAPIKeyEntries() CredentialSet {
+	file := paths.SharedCredentialsPath()
+	if env := strings.TrimSpace(os.Getenv(APIKeyEnv)); env != "" {
+		entry := ApiKeyEntry{Label: "env", Key: env, Default: true, Source: "env"}
+		return CredentialSet{Mode: "env-single", Entries: []ApiKeyEntry{entry}, DefaultEntry: &entry, Location: APIKeyEnv}
+	}
+
+	data := readSharedCredentials()
+	legacyRaw, _ := data[apiKeyField].(string)
+	legacy := strings.TrimSpace(legacyRaw) != ""
+	kc := keychainValue()
+
+	if _, ok := data[apiKeysField]; ok {
+		var warnings []string
+		stored := normalizeStoredEntries(data[apiKeysField], &warnings)
+		hasDefault := false
+		for _, e := range stored {
+			if e.Default {
+				hasDefault = true
+				break
+			}
+		}
+		if len(stored) > 0 && !hasDefault {
+			warnings = append(warnings, "apiKeys[] 未标记 default，运行时使用第一条 label="+stored[0].Label)
+		}
+		entries := toRuntimeEntries(stored)
+		return CredentialSet{
+			Mode: "file-multi", Entries: entries, DefaultEntry: pickDefault(entries), Location: file,
+			LegacyAPIKeyPresent: legacy, ShadowedKeychainPresent: kc != "", Warnings: warnings,
+		}
+	}
+
+	if kc != "" {
+		entry := ApiKeyEntry{Label: "keychain", Key: kc, Default: true, Source: "keychain"}
+		return CredentialSet{Mode: "keychain-single", Entries: []ApiKeyEntry{entry}, DefaultEntry: &entry,
+			Location: KeychainService + "/" + KeychainAPIKeyAccount, LegacyAPIKeyPresent: legacy}
+	}
+
+	if legacy {
+		val := strings.TrimSpace(legacyRaw)
+		entry := ApiKeyEntry{Label: "default", Key: val, Default: true, Source: "file"}
+		return CredentialSet{Mode: "legacy-file-single", Entries: []ApiKeyEntry{entry}, DefaultEntry: &entry,
+			Location: file, LegacyAPIKeyPresent: true}
+	}
+
+	return CredentialSet{Mode: "none", Location: file}
+}
+
+// ResolveAPIKey 返回当前默认 api-key。
+func ResolveAPIKey() ApiKeyResolution {
+	set := ResolveAPIKeyEntries()
+	if set.DefaultEntry == nil {
+		return ApiKeyResolution{Source: "none", Location: set.Location}
+	}
+	e := set.DefaultEntry
+	return ApiKeyResolution{Value: e.Key, Source: e.Source, Location: set.Location, Label: e.Label}
+}
+
+// SetAPIKey 写入 account 级 api-key。默认写共享文件；useKeychain 时写 OS keychain。
+func SetAPIKey(key string, useKeychain bool) (ApiKeyResolution, error) {
+	trimmed := strings.TrimSpace(key)
+	if trimmed == "" {
+		return ApiKeyResolution{}, errs.New(errs.CodeInvalidArgument, "api-key 不能为空")
+	}
+	if useKeychain {
+		data := readSharedCredentials()
+		if _, ok := data[apiKeysField]; ok {
+			return ApiKeyResolution{}, errs.New(errs.CodeKeychainMultiUnsupport,
+				"multi-key 模式不支持 --keychain；请使用文件 apiKeys[] 管理多 key")
+		}
+		if !keychain.Set(KeychainService, KeychainAPIKeyAccount, trimmed) {
+			return ApiKeyResolution{}, errs.New(errs.CodeKeychainUnavailable,
+				"当前平台无法写入 keychain，请去掉 --keychain 改写共享文件")
+		}
+		return ApiKeyResolution{Value: trimmed, Source: "keychain",
+			Location: KeychainService + "/" + KeychainAPIKeyAccount, Label: "keychain"}, nil
+	}
+	data := readSharedCredentials()
+	if _, ok := data[apiKeysField]; ok {
+		entries := storedEntriesFromFile(data)
+		if len(entries) == 0 {
+			return writeAPIKeys([]storedEntry{{Label: "default", Key: trimmed, Default: true, CreatedAt: nowISO()}})
+		}
+		idx := 0
+		for i, e := range entries {
+			if e.Default {
+				idx = i
+				break
+			}
+		}
+		for i := range entries {
+			entries[i].Default = i == idx
+			if i == idx {
+				entries[i].Key = trimmed
+			}
+		}
+		return writeAPIKeys(entries)
+	}
+	data[apiKeyField] = trimmed
+	if err := writeSharedCredentials(data); err != nil {
+		return ApiKeyResolution{}, err
+	}
+	return ApiKeyResolution{Value: trimmed, Source: "file", Location: paths.SharedCredentialsPath(), Label: "default"}, nil
+}
+
+// AddAPIKey 新增一条 multi-key api-key。
+func AddAPIKey(key, label string, makeDefault, force bool) (ApiKeyResolution, error) {
+	trimmed := strings.TrimSpace(key)
+	if trimmed == "" {
+		return ApiKeyResolution{}, errs.New(errs.CodeInvalidArgument, "api-key 不能为空")
+	}
+	if err := AssertValidAPIKeyLabel(label); err != nil {
+		return ApiKeyResolution{}, err
+	}
+	data := readSharedCredentials()
+	var entries []storedEntry
+	if _, ok := data[apiKeysField]; ok {
+		entries = storedEntriesFromFile(data)
+	} else if legacy := strings.TrimSpace(getString(data, apiKeyField)); legacy != "" {
+		entries = []storedEntry{{Label: "default", Key: legacy, Default: true, CreatedAt: nowISO()}}
+	}
+
+	existingIdx := indexOfLabel(entries, label)
+	if existingIdx >= 0 && !force {
+		return ApiKeyResolution{}, errs.New(errs.CodeAPIKeyLabelDuplicate, "api-key label 已存在："+label,
+			map[string]any{"hint": "如需覆盖，追加 --force", "label": label})
+	}
+
+	shouldDefault := makeDefault || len(entries) == 0
+	created := nowISO()
+	if existingIdx >= 0 {
+		created = entries[existingIdx].CreatedAt
+	}
+	next := storedEntry{Label: label, Key: trimmed, Default: shouldDefault, CreatedAt: created}
+	if existingIdx >= 0 {
+		entries[existingIdx] = next
+	} else {
+		entries = append(entries, next)
+	}
+	if shouldDefault {
+		for i := range entries {
+			entries[i].Default = entries[i].Label == label
+		}
+	} else {
+		hasDefault := false
+		for _, e := range entries {
+			if e.Default {
+				hasDefault = true
+				break
+			}
+		}
+		if !hasDefault && len(entries) > 0 {
+			entries[0].Default = true
+		}
+	}
+	return writeAPIKeys(entries)
+}
+
+// RemoveAPIKey 删除指定 label 的 api-key。
+func RemoveAPIKey(label string) (res ApiKeyResolution, removed, newDefault string, err error) {
+	if err = AssertValidAPIKeyLabel(label); err != nil {
+		return
+	}
+	data := readSharedCredentials()
+	var entries []storedEntry
+	if _, ok := data[apiKeysField]; ok {
+		entries = storedEntriesFromFile(data)
+	} else if legacy := strings.TrimSpace(getString(data, apiKeyField)); legacy != "" {
+		entries = []storedEntry{{Label: "default", Key: legacy, Default: true, CreatedAt: nowISO()}}
+	}
+	idx := indexOfLabel(entries, label)
+	if idx < 0 {
+		err = errs.New(errs.CodeAPIKeyLabelNotFound, "api-key label 不存在："+label, map[string]any{"label": label})
+		return
+	}
+	removedDefault := entries[idx].Default
+	var next []storedEntry
+	for _, e := range entries {
+		if e.Label != label {
+			next = append(next, e)
+		}
+	}
+	hasDefault := false
+	for _, e := range next {
+		if e.Default {
+			hasDefault = true
+			break
+		}
+	}
+	if len(next) > 0 && (removedDefault || !hasDefault) {
+		for i := range next {
+			next[i].Default = i == 0
+		}
+	}
+	res, err = writeAPIKeys(next)
+	return res, label, res.Label, err
+}
+
+// SetDefaultAPIKey 切换 default api-key。
+func SetDefaultAPIKey(label string) (ApiKeyResolution, error) {
+	if err := AssertValidAPIKeyLabel(label); err != nil {
+		return ApiKeyResolution{}, err
+	}
+	data := readSharedCredentials()
+	var entries []storedEntry
+	if _, ok := data[apiKeysField]; ok {
+		entries = storedEntriesFromFile(data)
+	}
+	if indexOfLabel(entries, label) < 0 {
+		return ApiKeyResolution{}, errs.New(errs.CodeAPIKeyLabelNotFound, "api-key label 不存在："+label, map[string]any{"label": label})
+	}
+	for i := range entries {
+		entries[i].Default = entries[i].Label == label
+	}
+	return writeAPIKeys(entries)
+}
+
+// MaskSecret 遮罩密钥用于展示。
+func MaskSecret(value string) string {
+	if value == "" {
+		return ""
+	}
+	if len(value) <= 8 {
+		return "***"
+	}
+	return value[:4] + "***" + value[len(value)-4:]
+}
+
+// ResolveGatewayToken 解析当前 profile 的 gateway token（按 config.auth.tokenRef）。
+func ResolveGatewayToken(cfg config.Config) (ResolvedRef, error) {
+	return ResolveRef(cfg.Auth.TokenRef)
+}
+
+// WriteGatewayToken 写入/轮换 gateway token。
+func WriteGatewayToken(cfg config.Config, value string) (ResolvedRef, error) {
+	return WriteRef(cfg.Auth.TokenRef, value)
+}
+
+// GenerateToken 生成一个随机 token（hex）。
+func GenerateToken(numBytes int) string {
+	if numBytes <= 0 {
+		numBytes = 32
+	}
+	b := make([]byte, numBytes)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+func indexOfLabel(entries []storedEntry, label string) int {
+	for i, e := range entries {
+		if e.Label == label {
+			return i
+		}
+	}
+	return -1
+}
+
+func getString(data map[string]any, key string) string {
+	s, _ := data[key].(string)
+	return s
+}
+
+func nowISO() string {
+	return time.Now().UTC().Format("2006-01-02T15:04:05.000Z")
+}
diff --git a/internal/daemon/lock.go b/internal/daemon/lock.go
new file mode 100644
index 0000000..c7ca883
--- /dev/null
+++ b/internal/daemon/lock.go
@@ -0,0 +1,46 @@
+// Package daemon 实现守护进程：进程锁、HTTP server、Relay 隧道装配。
+//
+// Phase 1 仅提供锁的读取面（status / doctor 需要探活）；写入面与主循环在 Phase 2。
+package daemon
+
+import (
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// Lock 是 daemon.lock 的内容。
+type Lock struct {
+	PID       int    `json:"pid"`
+	StartedAt string `json:"startedAt"`
+	Bind      string `json:"bind"`
+	Port      int    `json:"port"`
+	LogLevel  string `json:"logLevel,omitempty"`
+}
+
+// RunningState 是 daemon 运行态。
+type RunningState struct {
+	Running bool
+	Lock    *Lock
+	// Stale 锁存在但进程已死。
+	Stale bool
+}
+
+// ReadLock 读取锁文件；不存在返回 nil。
+func ReadLock(p paths.Paths) *Lock {
+	var lock Lock
+	exists, err := fsutil.ReadJSON(p.DaemonLock, &lock)
+	if err != nil || !exists {
+		return nil
+	}
+	return &lock
+}
+
+// State 返回 daemon 运行态（通过 signal 0 探活；陈旧锁视为未运行）。
+func State(p paths.Paths) RunningState {
+	lock := ReadLock(p)
+	if lock == nil {
+		return RunningState{}
+	}
+	alive := isProcessAlive(lock.PID)
+	return RunningState{Running: alive, Lock: lock, Stale: !alive}
+}
diff --git a/internal/daemon/proc_unix.go b/internal/daemon/proc_unix.go
new file mode 100644
index 0000000..47ffdeb
--- /dev/null
+++ b/internal/daemon/proc_unix.go
@@ -0,0 +1,20 @@
+//go:build !windows
+
+package daemon
+
+import (
+	"errors"
+	"syscall"
+)
+
+// isProcessAlive 用 signal 0 探活：nil=存活；EPERM=存在但无权限（仍算存活）；ESRCH=不存在。
+func isProcessAlive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	err := syscall.Kill(pid, 0)
+	if err == nil {
+		return true
+	}
+	return errors.Is(err, syscall.EPERM)
+}
diff --git a/internal/daemon/proc_windows.go b/internal/daemon/proc_windows.go
new file mode 100644
index 0000000..6de8205
--- /dev/null
+++ b/internal/daemon/proc_windows.go
@@ -0,0 +1,15 @@
+//go:build windows
+
+package daemon
+
+import "os"
+
+// isProcessAlive 在 Windows 上 best-effort：FindProcess 成功即视为存活。
+// （daemon 主要运行于 unix；Windows 探活精度有限，Phase 2 视需要再加固。）
+func isProcessAlive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	_, err := os.FindProcess(pid)
+	return err == nil
+}
diff --git a/internal/errs/errors.go b/internal/errs/errors.go
new file mode 100644
index 0000000..4fb0ea7
--- /dev/null
+++ b/internal/errs/errors.go
@@ -0,0 +1,80 @@
+// Package errs 提供携带结构化错误码的 CLI 错误（对齐 TS 版 src/errors.ts）。
+//
+// 命令失败时顶层统一序列化为 {ok:false, error:{code,message,...}}（见 internal/output）。
+package errs
+
+import "fmt"
+
+// 错误码常量，命名前缀统一 YOOOCLAW_*，进入半正式契约。
+const (
+	CodeUnknown                = "YOOOCLAW_UNKNOWN"
+	CodeInvalidArgument        = "YOOOCLAW_INVALID_ARGUMENT"
+	CodeNotImplemented         = "YOOOCLAW_NOT_IMPLEMENTED"
+	CodeDaemonNotRunning       = "YOOOCLAW_DAEMON_NOT_RUNNING"
+	CodeDaemonAlreadyRunning   = "YOOOCLAW_DAEMON_ALREADY_RUNNING"
+	CodeUnauthorized           = "YOOOCLAW_UNAUTHORIZED"
+	CodeConfigInvalid          = "YOOOCLAW_CONFIG_INVALID"
+	CodeProfileNotFound        = "YOOOCLAW_PROFILE_NOT_FOUND"
+	CodeImageNotReady          = "YOOOCLAW_IMAGE_NOT_READY"
+	CodeNotFound               = "YOOOCLAW_NOT_FOUND"
+	CodeAlreadyExists          = "YOOOCLAW_ALREADY_EXISTS"
+	CodeStorageUnavailable     = "YOOOCLAW_STORAGE_UNAVAILABLE"
+	CodeCredentialMissing      = "YOOOCLAW_CREDENTIAL_MISSING"
+	CodeKeychainUnavailable    = "YOOOCLAW_KEYCHAIN_UNAVAILABLE"
+	CodeAPIKeyLabelInvalid     = "YOOOCLAW_APIKEY_LABEL_INVALID"
+	CodeAPIKeyLabelDuplicate   = "YOOOCLAW_APIKEY_LABEL_DUPLICATE"
+	CodeAPIKeyLabelNotFound    = "YOOOCLAW_APIKEY_LABEL_NOT_FOUND"
+	CodeKeychainMultiUnsupport = "YOOOCLAW_KEYCHAIN_MULTI_UNSUPPORTED"
+	CodeTunnelLabelNotFound    = "YOOOCLAW_TUNNEL_LABEL_NOT_FOUND"
+	CodeNetworkError           = "YOOOCLAW_NETWORK_ERROR"
+	CodeConfirmationRequired   = "YOOOCLAW_CONFIRMATION_REQUIRED"
+	CodeNotInteractive         = "YOOOCLAW_NOT_INTERACTIVE"
+)
+
+// Error 携带结构化错误码、提示与进程退出码。
+type Error struct {
+	Code     string
+	Message  string
+	Details  map[string]any
+	ExitCode int
+}
+
+func (e *Error) Error() string { return e.Message }
+
+// Payload 序列化为统一错误 schema（code/message + 展开 details）。
+func (e *Error) Payload() map[string]any {
+	out := map[string]any{"code": e.Code, "message": e.Message}
+	for k, v := range e.Details {
+		out[k] = v
+	}
+	return out
+}
+
+// New 构造一个 Error，退出码默认 1。details 可选传入一个键值表。
+func New(code, message string, details ...map[string]any) *Error {
+	e := &Error{Code: code, Message: message, ExitCode: 1, Details: map[string]any{}}
+	if len(details) > 0 && details[0] != nil {
+		e.Details = details[0]
+	}
+	return e
+}
+
+// Newf 同 New，message 走 fmt.Sprintf。
+func Newf(code, format string, args ...any) *Error {
+	return New(code, fmt.Sprintf(format, args...))
+}
+
+// WithHint 链式补充 hint 提示。
+func (e *Error) WithHint(hint string) *Error {
+	if e.Details == nil {
+		e.Details = map[string]any{}
+	}
+	e.Details["hint"] = hint
+	return e
+}
+
+// NotImplemented 返回脚手架占位错误。
+func NotImplemented(command string) *Error {
+	return New(CodeNotImplemented, fmt.Sprintf("命令 `%s` 尚未实现", command)).
+		WithHint("该命令处于脚手架阶段，后续逐步落地")
+}
diff --git a/internal/fsutil/fsutil.go b/internal/fsutil/fsutil.go
new file mode 100644
index 0000000..80adfda
--- /dev/null
+++ b/internal/fsutil/fsutil.go
@@ -0,0 +1,95 @@
+// Package fsutil 统一目录/文件权限与原子写（对齐 TS 版 src/fs-utils.ts）。
+//
+// 安全约束：目录 0700、敏感文件 0600；写入走「临时文件 + rename」原子替换。
+package fsutil
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/YoooClaw/cli/internal/errs"
+)
+
+const (
+	// DirMode 目录默认权限（私有）。
+	DirMode os.FileMode = 0o700
+	// SecretFileMode 敏感文件权限（仅属主可读写）。
+	SecretFileMode os.FileMode = 0o600
+	// ConfigFileMode 普通配置文件权限。
+	ConfigFileMode os.FileMode = 0o644
+)
+
+// EnsureDir 确保目录存在并尽力收紧权限（Windows 上 chmod 基本 no-op）。
+func EnsureDir(dir string, mode os.FileMode) error {
+	if mode == 0 {
+		mode = DirMode
+	}
+	if err := os.MkdirAll(dir, mode); err != nil {
+		return err
+	}
+	_ = os.Chmod(dir, mode) // Windows / 受限 FS 忽略
+	return nil
+}
+
+func randSuffix() string {
+	b := make([]byte, 6)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+// WriteAtomic 原子写文件：先写临时文件再 rename，最后 chmod。
+func WriteAtomic(path string, data []byte, mode os.FileMode) error {
+	if mode == 0 {
+		mode = ConfigFileMode
+	}
+	dir := filepath.Dir(path)
+	if err := EnsureDir(dir, DirMode); err != nil {
+		return err
+	}
+	tmp := filepath.Join(dir, fmt.Sprintf(".%s.tmp", randSuffix()))
+	if err := os.WriteFile(tmp, data, mode); err != nil {
+		return err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		_ = os.Remove(tmp)
+		return err
+	}
+	_ = os.Chmod(path, mode)
+	return nil
+}
+
+// WriteJSON 写 JSON（两空格缩进 + 末尾换行）。
+func WriteJSON(path string, v any, mode os.FileMode) error {
+	data, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return err
+	}
+	data = append(data, '\n')
+	return WriteAtomic(path, data, mode)
+}
+
+// ReadJSON 读 JSON 到 out；文件不存在返回 (false, nil)；解析失败返回 CONFIG_INVALID。
+func ReadJSON(path string, out any) (exists bool, err error) {
+	raw, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	if err != nil {
+		return false, errs.New(errs.CodeConfigInvalid, "读取文件失败："+path)
+	}
+	if err := json.Unmarshal(raw, out); err != nil {
+		return true, errs.New(errs.CodeConfigInvalid, "文件不是合法 JSON："+path).
+			WithHint("可手动修复或删除后重新生成")
+	}
+	return true, nil
+}
+
+// Exists 报告路径是否存在。
+func Exists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
diff --git a/internal/keychain/keychain.go b/internal/keychain/keychain.go
new file mode 100644
index 0000000..ada1ac1
--- /dev/null
+++ b/internal/keychain/keychain.go
@@ -0,0 +1,84 @@
+// Package keychain 适配 OS keychain（可选加固，默认不强制）。
+//
+//   - macOS：security（generic password）
+//   - Linux：secret-tool（libsecret / Secret Service）
+//   - Windows：暂无可明文取回的内置 CLI → 视为不可用，调用方降级到文件
+//
+// 任何工具缺失 / 调用失败都返回不可用，绝不崩溃，保证 CI 无 keychain 时的确定性。
+package keychain
+
+import (
+	"os/exec"
+	"runtime"
+	"strings"
+)
+
+// Result 是 keychain 读取结果。
+type Result struct {
+	Available bool
+	Value     string
+}
+
+func hasCommand(cmd string) bool {
+	_, err := exec.LookPath(cmd)
+	return err == nil
+}
+
+// Available 报告当前平台 keychain 是否可用（工具存在）。
+func Available() bool {
+	switch runtime.GOOS {
+	case "darwin":
+		return hasCommand("security")
+	case "linux":
+		return hasCommand("secret-tool")
+	default:
+		return false
+	}
+}
+
+// Get 读取 keychain 条目；不可用或未命中返回 Value=""。
+func Get(service, account string) Result {
+	switch runtime.GOOS {
+	case "darwin":
+		if !hasCommand("security") {
+			return Result{Available: false}
+		}
+		out, err := exec.Command("security", "find-generic-password", "-s", service, "-a", account, "-w").Output()
+		if err != nil {
+			return Result{Available: true}
+		}
+		return Result{Available: true, Value: strings.TrimRight(string(out), "\n")}
+	case "linux":
+		if !hasCommand("secret-tool") {
+			return Result{Available: false}
+		}
+		out, err := exec.Command("secret-tool", "lookup", "service", service, "account", account).Output()
+		if err != nil {
+			return Result{Available: true}
+		}
+		return Result{Available: true, Value: strings.TrimRight(string(out), "\n")}
+	default:
+		return Result{Available: false}
+	}
+}
+
+// Set 写入 keychain 条目；返回是否成功。
+func Set(service, account, value string) bool {
+	switch runtime.GOOS {
+	case "darwin":
+		if !hasCommand("security") {
+			return false
+		}
+		err := exec.Command("security", "add-generic-password", "-U", "-s", service, "-a", account, "-w", value).Run()
+		return err == nil
+	case "linux":
+		if !hasCommand("secret-tool") {
+			return false
+		}
+		cmd := exec.Command("secret-tool", "store", "--label", service+":"+account, "service", service, "account", account)
+		cmd.Stdin = strings.NewReader(value)
+		return cmd.Run() == nil
+	default:
+		return false
+	}
+}
diff --git a/internal/notif/query.go b/internal/notif/query.go
new file mode 100644
index 0000000..e1929ff
--- /dev/null
+++ b/internal/notif/query.go
@@ -0,0 +1,303 @@
+package notif
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/errs"
+)
+
+var isoRE = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$`)
+var dateFileRE = regexp.MustCompile(`^(\d{4}-\d{2}-\d{2})\.json$`)
+
+// QueryOptions 是解析后的查询条件。
+type QueryOptions struct {
+	App              string
+	Sender           string
+	ConversationType string
+	Keyword          string
+	Client           string
+	Limit            int
+	FromTs           *time.Time
+	ToTs             *time.Time
+	FromDateKey      string
+	ToDateKey        string
+}
+
+// RawQueryOpts 是命令行原始字符串参数。
+type RawQueryOpts struct {
+	From             string
+	To               string
+	App              string
+	Sender           string
+	ConversationType string
+	Keyword          string
+	Client           string
+	Limit            string
+}
+
+// ParseTime 解析 ISO 8601 时间（容忍无秒/带毫秒）。
+func ParseTime(value string) (time.Time, bool) {
+	for _, layout := range []string{
+		time.RFC3339Nano, time.RFC3339,
+		"2006-01-02T15:04Z07:00", "2006-01-02T15:04:05.000Z07:00",
+	} {
+		if t, err := time.Parse(layout, value); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}
+
+func parseIso(value, name string) (time.Time, error) {
+	if !isoRE.MatchString(value) {
+		return time.Time{}, errs.Newf(errs.CodeInvalidArgument, "%s 必须是 ISO 8601 时间，例如 2026-03-01T09:00:00+08:00", name)
+	}
+	t, ok := ParseTime(value)
+	if !ok {
+		return time.Time{}, errs.Newf(errs.CodeInvalidArgument, "%s 不是合法时间", name)
+	}
+	return t, nil
+}
+
+func parseLimit(raw string, fallback int) (int, error) {
+	if raw == "" {
+		return fallback, nil
+	}
+	n, err := strconv.Atoi(raw)
+	if err != nil || n <= 0 {
+		return 0, errs.New(errs.CodeInvalidArgument, "--limit 必须是大于 0 的整数")
+	}
+	return n, nil
+}
+
+// BuildQueryOptions 校验并构造 QueryOptions。
+func BuildQueryOptions(opts RawQueryOpts, defaultLimit int) (QueryOptions, error) {
+	if opts.ConversationType != "" && opts.ConversationType != "group" && opts.ConversationType != "private" {
+		return QueryOptions{}, errs.New(errs.CodeInvalidArgument, "--conversation-type 只能是 group 或 private")
+	}
+	out := QueryOptions{
+		App: opts.App, Sender: opts.Sender, ConversationType: opts.ConversationType,
+		Keyword: opts.Keyword, Client: opts.Client,
+	}
+	if opts.From != "" {
+		t, err := parseIso(opts.From, "--from")
+		if err != nil {
+			return QueryOptions{}, err
+		}
+		out.FromTs = &t
+		out.FromDateKey = opts.From[:10]
+	}
+	if opts.To != "" {
+		t, err := parseIso(opts.To, "--to")
+		if err != nil {
+			return QueryOptions{}, err
+		}
+		out.ToTs = &t
+		out.ToDateKey = opts.To[:10]
+	}
+	if out.FromTs != nil && out.ToTs != nil && out.FromTs.After(*out.ToTs) {
+		return QueryOptions{}, errs.New(errs.CodeInvalidArgument, "--from 不能晚于 --to")
+	}
+	limit, err := parseLimit(opts.Limit, defaultLimit)
+	if err != nil {
+		return QueryOptions{}, err
+	}
+	out.Limit = limit
+	return out, nil
+}
+
+// Query 收集匹配的通知；目录不存在返回空（无 daemon / 尚无数据是正常态）。
+func Query(notificationsDir string, opts QueryOptions) []StoredNotification {
+	if !dirExists(notificationsDir) {
+		return nil
+	}
+	return collectMatching(notificationsDir, opts)
+}
+
+func dirExists(dir string) bool {
+	info, err := os.Stat(dir)
+	return err == nil && info.IsDir()
+}
+
+// listDateKeys 列出 YYYY-MM-DD 日期 key，降序。
+func listDateKeys(dir string) []string {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+	var keys []string
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		if m := dateFileRE.FindStringSubmatch(e.Name()); m != nil {
+			keys = append(keys, m[1])
+		}
+	}
+	sort.Sort(sort.Reverse(sort.StringSlice(keys)))
+	return keys
+}
+
+func readDateFile(dir, dateKey string) []StoredNotification {
+	raw, err := os.ReadFile(filepath.Join(dir, dateKey+".json"))
+	if err != nil {
+		return nil
+	}
+	var items []StoredNotification
+	if json.Unmarshal(raw, &items) != nil {
+		return nil
+	}
+	return items
+}
+
+func sortByTimestampDesc(items []StoredNotification) {
+	sort.SliceStable(items, func(i, j int) bool {
+		ti, _ := ParseTime(items[i].Timestamp)
+		tj, _ := ParseTime(items[j].Timestamp)
+		return ti.After(tj)
+	})
+}
+
+func collectMatching(dir string, opts QueryOptions) []StoredNotification {
+	keys := listDateKeys(dir)
+	var results []StoredNotification
+	canStop := opts.FromTs == nil && opts.ToTs == nil
+
+	for _, dateKey := range keys {
+		if opts.FromDateKey != "" && dateKey < opts.FromDateKey {
+			continue
+		}
+		if opts.ToDateKey != "" && dateKey > opts.ToDateKey {
+			continue
+		}
+		items := readDateFile(dir, dateKey)
+		sortByTimestampDesc(items)
+		for _, item := range items {
+			if !MatchesQuery(item, opts) {
+				continue
+			}
+			results = append(results, item)
+			if canStop && len(results) >= opts.Limit {
+				return results
+			}
+		}
+	}
+	sortByTimestampDesc(results)
+	if len(results) > opts.Limit {
+		results = results[:opts.Limit]
+	}
+	return results
+}
+
+// MatchesQuery 判断单条通知是否命中查询条件。
+func MatchesQuery(item StoredNotification, opts QueryOptions) bool {
+	if opts.Client != "" && opts.Client != "all" {
+		label := item.ClientLabel
+		if label == "" {
+			label = "legacy"
+		}
+		if label != opts.Client {
+			return false
+		}
+	}
+	if opts.App != "" && !MatchesAppFilter(item, opts.App) {
+		return false
+	}
+	if opts.ConversationType != "" && item.ConversationType != opts.ConversationType {
+		return false
+	}
+	if opts.Sender != "" {
+		hay := joinNonEmpty([]string{item.SenderName, item.Title}, "\n")
+		if !strings.Contains(hay, opts.Sender) {
+			return false
+		}
+	}
+	if opts.Keyword != "" {
+		hay := joinNonEmpty([]string{item.Title, item.Content, item.SenderName, item.ConversationName}, "\n")
+		if !strings.Contains(hay, opts.Keyword) {
+			return false
+		}
+	}
+	ts, ok := ParseTime(item.Timestamp)
+	if !ok {
+		return false
+	}
+	if opts.FromTs != nil && ts.Before(*opts.FromTs) {
+		return false
+	}
+	if opts.ToTs != nil && ts.After(*opts.ToTs) {
+		return false
+	}
+	return true
+}
+
+var appAliasGroups = [][]string{
+	{"微信", "wechat", "weixin", "com.tencent.mm", "com.tencent.xin"},
+	{"企业微信", "wecom", "wxwork", "com.tencent.wework"},
+	{"飞书", "feishu", "lark", "com.ss.android.lark", "com.bytedance.ee.lark", "com.larksuite.suite"},
+	{"钉钉", "dingtalk", "com.alibaba.android.rimet"},
+	{"qq", "腾讯qq", "com.tencent.mobileqq"},
+}
+
+func normalizeLookup(v string) string { return strings.ToLower(strings.TrimSpace(v)) }
+
+// appAliasGroupIndex 返回 value 所属别名组的下标，-1 表示无。
+func appAliasGroupIndex(value string) int {
+	n := normalizeLookup(value)
+	if n == "" {
+		return -1
+	}
+	for gi, group := range appAliasGroups {
+		for _, cand := range group {
+			if normalizeLookup(cand) == n {
+				return gi
+			}
+		}
+	}
+	return -1
+}
+
+// MatchesAppFilter 判断通知是否匹配 --app 过滤（支持中英文别名）。
+func MatchesAppFilter(item StoredNotification, app string) bool {
+	filter := normalizeLookup(app)
+	if filter == "" {
+		return true
+	}
+	candidates := nonEmpty([]string{item.AppName, item.AppDisplayName})
+	for _, c := range candidates {
+		if normalizeLookup(c) == filter {
+			return true
+		}
+	}
+	fg := appAliasGroupIndex(app)
+	if fg < 0 {
+		return false
+	}
+	for _, c := range candidates {
+		if appAliasGroupIndex(c) == fg {
+			return true
+		}
+	}
+	return false
+}
+
+func nonEmpty(values []string) []string {
+	var out []string
+	for _, v := range values {
+		if v != "" {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+func joinNonEmpty(values []string, sep string) string {
+	return strings.Join(nonEmpty(values), sep)
+}
diff --git a/internal/notif/types.go b/internal/notif/types.go
new file mode 100644
index 0000000..8e08493
--- /dev/null
+++ b/internal/notif/types.go
@@ -0,0 +1,41 @@
+// Package notif 提供通知的存储模型、查询匹配与（Phase 2）落盘去重逻辑，
+// 对齐 phone-notifications 的 storage.ts / cli ntf-query.ts。
+package notif
+
+// StoredNotification 是落盘的通知条目（date-keyed JSON 数组的元素）。
+type StoredNotification struct {
+	// ClientLabel 来源客户端 label；旧数据无该字段，查询时视为 legacy。
+	ClientLabel string `json:"clientLabel,omitempty"`
+	// AppName 包名。
+	AppName string `json:"appName"`
+	// AppDisplayName 应用显示名（缺省时与 AppName 一致）。
+	AppDisplayName string `json:"appDisplayName,omitempty"`
+	Title          string `json:"title"`
+	Content        string `json:"content"`
+	// Timestamp ISO 8601 含时区。
+	Timestamp string `json:"timestamp"`
+	// SenderName 结构化发送人（主要用于飞书）。
+	SenderName string `json:"senderName,omitempty"`
+	// ConversationType private | group。
+	ConversationType string `json:"conversationType,omitempty"`
+	// ConversationName 结构化会话名（主要用于飞书群名）。
+	ConversationName string `json:"conversationName,omitempty"`
+}
+
+// RawNotification 是手机端上报 / HTTP ingest 的原始通知。
+type RawNotification struct {
+	ID        string         `json:"id"`
+	App       string         `json:"app"`
+	Title     string         `json:"title"`
+	Body      string         `json:"body"`
+	Timestamp string         `json:"timestamp"`
+	Category  string         `json:"category,omitempty"`
+	Metadata  map[string]any `json:"metadata,omitempty"`
+}
+
+// PluginConfig 是存储层关心的配置子集。
+type PluginConfig struct {
+	// RetentionDays 为 nil 表示永久保存。
+	RetentionDays *int
+	IgnoredApps   []string
+}
diff --git a/internal/output/output.go b/internal/output/output.go
new file mode 100644
index 0000000..2258259
--- /dev/null
+++ b/internal/output/output.go
@@ -0,0 +1,201 @@
+// Package output 统一所有命令的 stdout 序列化（对齐 TS 版 src/output/format.ts）。
+//
+// 支持 --format json|pretty|table|ndjson；错误与正常输出共用 {ok:false,error:{...}} schema。
+package output
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"sort"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/errs"
+)
+
+// Format 是输出格式。
+type Format string
+
+const (
+	JSON   Format = "json"
+	Pretty Format = "pretty"
+	Table  Format = "table"
+	NDJSON Format = "ndjson"
+)
+
+var allFormats = []Format{JSON, Pretty, Table, NDJSON}
+
+// ResolveFormat 解析 --format；auto/空时按 TTY 判定（pretty / json）。
+func ResolveFormat(requested string, isTTY bool) (Format, error) {
+	if requested != "" && requested != "auto" {
+		for _, f := range allFormats {
+			if string(f) == requested {
+				return f, nil
+			}
+		}
+		return "", errs.New(errs.CodeInvalidArgument, "不支持的输出格式："+requested).
+			WithHint("可选值：json | pretty | table | ndjson | auto")
+	}
+	if isTTY {
+		return Pretty, nil
+	}
+	return JSON, nil
+}
+
+// StdoutIsTTY 报告 stdout 是否为终端。
+func StdoutIsTTY() bool {
+	info, err := os.Stdout.Stat()
+	if err != nil {
+		return false
+	}
+	return info.Mode()&os.ModeCharDevice != 0
+}
+
+// marshalJSON 序列化为 JSON，不转义 HTML（与 JS JSON.stringify 对齐）。
+func marshalJSON(v any, indent bool) string {
+	var buf bytes.Buffer
+	enc := json.NewEncoder(&buf)
+	enc.SetEscapeHTML(false)
+	if indent {
+		enc.SetIndent("", "  ")
+	}
+	if err := enc.Encode(v); err != nil {
+		return fmt.Sprintf("%v", v)
+	}
+	return strings.TrimRight(buf.String(), "\n")
+}
+
+func writeLine(w io.Writer, text string) {
+	if !strings.HasSuffix(text, "\n") {
+		text += "\n"
+	}
+	_, _ = io.WriteString(w, text)
+}
+
+// RenderResult 渲染一次成功结果到 w。
+func RenderResult(w io.Writer, data any, format Format) {
+	switch format {
+	case JSON:
+		writeLine(w, marshalJSON(data, false))
+	case Pretty:
+		writeLine(w, marshalJSON(data, true))
+	case NDJSON:
+		for _, row := range toRows(data) {
+			writeLine(w, marshalJSON(row, false))
+		}
+	case Table:
+		writeLine(w, renderTable(data))
+	}
+}
+
+// RenderError 渲染错误（统一 {ok:false,error:{...}} schema）。
+func RenderError(w io.Writer, err error, format Format) {
+	var payloadErr map[string]any
+	var ye *errs.Error
+	if e, ok := err.(*errs.Error); ok {
+		ye = e
+	}
+	if ye != nil {
+		payloadErr = ye.Payload()
+	} else {
+		payloadErr = map[string]any{"code": errs.CodeUnknown, "message": err.Error()}
+	}
+	payload := map[string]any{"ok": false, "error": payloadErr}
+	if format == Pretty {
+		writeLine(w, marshalJSON(payload, true))
+	} else {
+		writeLine(w, marshalJSON(payload, false))
+	}
+}
+
+func toRows(data any) []any {
+	if arr, ok := data.([]any); ok {
+		return arr
+	}
+	return []any{data}
+}
+
+// renderTable 极简表格渲染：对象数组 → 列对齐文本；其余 fallback 到 pretty JSON。
+func renderTable(data any) string {
+	arr, ok := data.([]any)
+	if !ok || len(arr) == 0 {
+		return marshalJSON(data, true)
+	}
+	rows := make([]map[string]any, 0, len(arr))
+	for _, r := range arr {
+		m, ok := r.(map[string]any)
+		if !ok {
+			return marshalJSON(data, true)
+		}
+		rows = append(rows, m)
+	}
+	var columns []string
+	seen := map[string]bool{}
+	for _, row := range rows {
+		keys := make([]string, 0, len(row))
+		for k := range row {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			if !seen[k] {
+				seen[k] = true
+				columns = append(columns, k)
+			}
+		}
+	}
+	cell := func(v any) string {
+		if v == nil {
+			return ""
+		}
+		switch t := v.(type) {
+		case string:
+			return t
+		case map[string]any, []any:
+			return marshalJSON(t, false)
+		default:
+			return fmt.Sprintf("%v", t)
+		}
+	}
+	widths := make([]int, len(columns))
+	for i, col := range columns {
+		widths[i] = len(col)
+		for _, row := range rows {
+			if l := len(cell(row[col])); l > widths[i] {
+				widths[i] = l
+			}
+		}
+	}
+	pad := func(s string, w int) string {
+		if len(s) < w {
+			return s + strings.Repeat(" ", w-len(s))
+		}
+		return s
+	}
+	var b strings.Builder
+	for i, col := range columns {
+		if i > 0 {
+			b.WriteString("  ")
+		}
+		b.WriteString(pad(col, widths[i]))
+	}
+	b.WriteString("\n")
+	for i, w := range widths {
+		if i > 0 {
+			b.WriteString("  ")
+		}
+		b.WriteString(strings.Repeat("-", w))
+	}
+	for _, row := range rows {
+		b.WriteString("\n")
+		for i, col := range columns {
+			if i > 0 {
+				b.WriteString("  ")
+			}
+			b.WriteString(pad(cell(row[col]), widths[i]))
+		}
+	}
+	return b.String()
+}
diff --git a/internal/paths/paths.go b/internal/paths/paths.go
new file mode 100644
index 0000000..b636fd4
--- /dev/null
+++ b/internal/paths/paths.go
@@ -0,0 +1,109 @@
+// Package paths 解析 ~/.yoooclaw/ 目录布局（对齐 TS 版 src/paths.ts）。
+//
+//	~/.yoooclaw/
+//	  credentials.json            account 级共享凭据（跨 profile 且与插件共享）
+//	  active-profile              当前 active profile 名（文本）
+//	  profiles/<profile>/
+//	    config.json
+//	    credentials.json          instance 级密文
+//	    daemon.lock / daemon.log
+//	    notifications/ recordings/ images/ light-rules/ state/
+package paths
+
+import (
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// DefaultProfile 是缺省 profile 名。
+const DefaultProfile = "default"
+
+// RootDir 返回 CLI 根数据目录。可用 YOOOCLAW_HOME 覆盖（测试 / 多实例隔离）。
+func RootDir() string {
+	if h := strings.TrimSpace(os.Getenv("YOOOCLAW_HOME")); h != "" {
+		return h
+	}
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".yoooclaw")
+}
+
+// SharedCredentialsPath 返回 account 级共享凭据文件（顶层，跨 profile + 插件共享）。
+func SharedCredentialsPath() string {
+	return filepath.Join(RootDir(), "credentials.json")
+}
+
+// ActiveProfilePath 返回记录当前 active profile 的文本文件路径。
+func ActiveProfilePath() string {
+	return filepath.Join(RootDir(), "active-profile")
+}
+
+// ProfileDir 返回某个 profile 的目录。
+func ProfileDir(profile string) string {
+	return filepath.Join(RootDir(), "profiles", profile)
+}
+
+// ProfilesRoot 返回 profiles/ 根目录。
+func ProfilesRoot() string {
+	return filepath.Join(RootDir(), "profiles")
+}
+
+// Paths 是某个 profile 下的全部关键路径。
+type Paths struct {
+	Profile       string
+	Dir           string
+	Config        string
+	Credentials   string
+	DaemonLock    string
+	DaemonLog     string
+	Notifications string
+	Recordings    string
+	Images        string
+	LightRules    string
+	State         string
+}
+
+// For 解析某个 profile 下的全部关键路径。
+func For(profile string) Paths {
+	dir := ProfileDir(profile)
+	return Paths{
+		Profile:       profile,
+		Dir:           dir,
+		Config:        filepath.Join(dir, "config.json"),
+		Credentials:   filepath.Join(dir, "credentials.json"),
+		DaemonLock:    filepath.Join(dir, "daemon.lock"),
+		DaemonLog:     filepath.Join(dir, "daemon.log"),
+		Notifications: filepath.Join(dir, "notifications"),
+		Recordings:    filepath.Join(dir, "recordings"),
+		Images:        filepath.Join(dir, "images"),
+		LightRules:    filepath.Join(dir, "light-rules"),
+		State:         filepath.Join(dir, "state"),
+	}
+}
+
+// ListProfileNames 列出已存在的 profile 名（profiles/ 下的目录），按名排序。
+func ListProfileNames() []string {
+	root := ProfilesRoot()
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		return nil
+	}
+	var names []string
+	for _, e := range entries {
+		if e.IsDir() {
+			names = append(names, e.Name())
+		}
+	}
+	sort.Strings(names)
+	return names
+}
+
+// ReadActiveProfile 读取 active-profile 文件内容（不存在或空返回 ""）。
+func ReadActiveProfile() string {
+	raw, err := os.ReadFile(ActiveProfilePath())
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(raw))
+}
diff --git a/internal/prompt/prompt.go b/internal/prompt/prompt.go
new file mode 100644
index 0000000..f9d5592
--- /dev/null
+++ b/internal/prompt/prompt.go
@@ -0,0 +1,79 @@
+// Package prompt 提供交互式输入工具（对齐 TS 版 src/prompt.ts）。
+//
+// 非 TTY 环境调用任何 prompt 都返回 NOT_INTERACTIVE，避免在管道里挂起。
+package prompt
+
+import (
+	"bufio"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/errs"
+)
+
+// IsInteractive 报告 stdin 与 stdout 是否都是 TTY。
+func IsInteractive() bool {
+	return isTTY(os.Stdin) && isTTY(os.Stdout)
+}
+
+func isTTY(f *os.File) bool {
+	info, err := f.Stat()
+	if err != nil {
+		return false
+	}
+	return info.Mode()&os.ModeCharDevice != 0
+}
+
+func ensureInteractive() error {
+	if !IsInteractive() {
+		return errs.New(errs.CodeNotInteractive, "当前为非交互环境，无法进行交互式输入").
+			WithHint("改用 --non-interactive --from-file，或在 TTY 中运行")
+	}
+	return nil
+}
+
+// Ask 提一个问题，返回去空白后的回答；提供 defaultValue 时回车采用默认。
+func Ask(question, defaultValue string) (string, error) {
+	if err := ensureInteractive(); err != nil {
+		return "", err
+	}
+	suffix := ""
+	if defaultValue != "" {
+		suffix = " [" + defaultValue + "]"
+	}
+	_, _ = io.WriteString(os.Stdout, question+suffix+": ")
+	reader := bufio.NewReader(os.Stdin)
+	line, _ := reader.ReadString('\n')
+	answer := strings.TrimSpace(line)
+	if answer == "" {
+		return defaultValue, nil
+	}
+	return answer, nil
+}
+
+// Confirm 是 Yes/No 确认，默认值由 defaultYes 决定。
+func Confirm(question string, defaultYes bool) (bool, error) {
+	hint := "y/N"
+	if defaultYes {
+		hint = "Y/n"
+	}
+	answer, err := Ask(question+" ("+hint+")", "")
+	if err != nil {
+		return false, err
+	}
+	answer = strings.ToLower(answer)
+	if answer == "" {
+		return defaultYes, nil
+	}
+	return answer == "y" || answer == "yes", nil
+}
+
+// ReadStdin 读取 stdin 全部内容（用于 --from-file - / set-api-key -）。
+func ReadStdin() (string, error) {
+	data, err := io.ReadAll(os.Stdin)
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
diff --git a/internal/version/version.go b/internal/version/version.go
new file mode 100644
index 0000000..763b181
--- /dev/null
+++ b/internal/version/version.go
@@ -0,0 +1,11 @@
+// Package version 暴露 CLI 版本号。
+//
+// Version 由构建期通过 -ldflags 注入，与 npm 包 version 同源：
+//
+//	go build -ldflags "-X github.com/YoooClaw/cli/internal/version.Version=<v>" ./cmd/yc
+//
+// 本地直接 go run/build 时回退为 "dev"。
+package version
+
+// Version 是 CLI 版本号；构建期注入，默认 "dev"。
+var Version = "dev"
diff --git a/npm/cli/README.md b/npm/cli/README.md
new file mode 100644
index 0000000..c680dbb
--- /dev/null
+++ b/npm/cli/README.md
@@ -0,0 +1,23 @@
+# @yoooclaw/cli
+
+yoooclaw 独立 CLI（Go 实现）。npm 包本身只含一个极薄的 Node launcher；真正的可执行
+是按平台分发的原生 Go 二进制，通过 `optionalDependencies` 子包安装，npm 会根据
+`os`/`cpu` 字段自动只装匹配当前平台的那一个。
+
+## 安装
+
+```bash
+npm i -g @yoooclaw/cli
+# 提供 yoooclaw 与 yc 两个命令
+yc --version
+```
+
+也可不经 npm，直接下载原生二进制（见 GitHub Release / install.sh）。
+
+## 支持平台
+
+| OS | Arch |
+|----|------|
+| macOS (darwin) | arm64, x64 |
+| Linux | x64, arm64 |
+| Windows (win32) | x64 |
diff --git a/npm/cli/bin/yc.js b/npm/cli/bin/yc.js
new file mode 100644
index 0000000..5720770
--- /dev/null
+++ b/npm/cli/bin/yc.js
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+"use strict";
+
+// @yoooclaw/cli launcher —— 解析当前平台对应的 optionalDependency 子包里的 Go
+// 二进制并执行它，透传 argv 与退出码。子包按 package.json 的 os/cpu 字段由 npm
+// 自动只安装匹配当前平台的那一个。
+//
+// 设计与 esbuild / turbo 一致：主包不含二进制，只含这个极薄 launcher。
+
+const { spawnSync } = require("node:child_process");
+
+function resolveBinary() {
+  const platform = process.platform; // darwin | linux | win32
+  const arch = process.arch; // arm64 | x64
+  const pkg = `@yoooclaw/cli-${platform}-${arch}`;
+  const binName = platform === "win32" ? "yc.exe" : "yc";
+  try {
+    return require.resolve(`${pkg}/bin/${binName}`);
+  } catch {
+    return null;
+  }
+}
+
+const bin = resolveBinary();
+if (!bin) {
+  const target = `${process.platform}-${process.arch}`;
+  process.stderr.write(
+    `@yoooclaw/cli: 找不到当前平台的二进制（${target}）。\n` +
+      "可能原因：\n" +
+      "  - 该平台暂不支持（当前支持 darwin/linux 的 x64+arm64、win32 的 x64）\n" +
+      "  - 安装时跳过了 optionalDependencies（--no-optional / --omit=optional）\n" +
+      "请尝试重新安装： npm i -g @yoooclaw/cli\n",
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+if (result.error) {
+  process.stderr.write(`@yoooclaw/cli: 启动二进制失败：${result.error.message}\n`);
+  process.exit(1);
+}
+// 子进程被信号杀死时 status 为 null；统一以非零码退出。
+process.exit(typeof result.status === "number" ? result.status : 1);
diff --git a/scripts/build-go.sh b/scripts/build-go.sh
new file mode 100755
index 0000000..3e90474
--- /dev/null
+++ b/scripts/build-go.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# 交叉编译 Go CLI，并装配 npm 分发产物（主 launcher 包 + 各平台子包）。
+#
+# 用法:
+#   scripts/build-go.sh [version]        # version 默认从 package.json 读，保持与 npm 版本同源
+#   scripts/build-go.sh --current        # 只构当前平台（本地快速验证）
+#
+# 产物:
+#   dist-native/yoooclaw-<os>-<arch>{,.exe}   原始二进制（GitHub Release / install.sh 用）
+#   dist-npm/cli/                             主 launcher 包 @yoooclaw/cli
+#   dist-npm/cli-<os>-<arch>/                 各平台子包 @yoooclaw/cli-<os>-<arch>
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+MODULE="github.com/YoooClaw/cli"
+
+# 解析参数：可选 --current，以及可选 version。
+CURRENT_ONLY=0
+VERSION=""
+for arg in "$@"; do
+  case "$arg" in
+    --current) CURRENT_ONLY=1 ;;
+    *) VERSION="$arg" ;;
+  esac
+done
+[ -n "$VERSION" ] || VERSION="$(node -p "require('./package.json').version")"
+
+LDFLAGS="-s -w -X ${MODULE}/internal/version.Version=${VERSION}"
+
+# 目标矩阵： GOOS:GOARCH:npmOs:npmCpu
+ALL_TARGETS="darwin:arm64:darwin:arm64 darwin:amd64:darwin:x64 linux:amd64:linux:x64 linux:arm64:linux:arm64 windows:amd64:win32:x64"
+if [ "$CURRENT_ONLY" -eq 1 ]; then
+  goos="$(go env GOOS)"; goarch="$(go env GOARCH)"
+  npmcpu="$goarch"; [ "$goarch" = "amd64" ] && npmcpu="x64"
+  npmos="$goos"; [ "$goos" = "windows" ] && npmos="win32"
+  TARGETS="${goos}:${goarch}:${npmos}:${npmcpu}"
+else
+  TARGETS="$ALL_TARGETS"
+fi
+
+rm -rf dist-native dist-npm
+mkdir -p dist-native dist-npm
+
+PLATFORM_PKGS=""
+
+for t in $TARGETS; do
+  GOOS="${t%%:*}";  rest="${t#*:}"
+  GOARCH="${rest%%:*}"; rest="${rest#*:}"
+  NPM_OS="${rest%%:*}"; NPM_CPU="${rest##*:}"
+
+  ext=""; bin="yc"
+  if [ "$GOOS" = "windows" ]; then ext=".exe"; bin="yc.exe"; fi
+  asset="yoooclaw-${NPM_OS}-${NPM_CPU}${ext}"
+
+  echo "==> go build $GOOS/$GOARCH -> dist-native/$asset"
+  CGO_ENABLED=0 GOOS="$GOOS" GOARCH="$GOARCH" \
+    go build -trimpath -ldflags "$LDFLAGS" -o "dist-native/$asset" ./cmd/yc
+
+  pkgdir="dist-npm/cli-${NPM_OS}-${NPM_CPU}"
+  mkdir -p "$pkgdir/bin"
+  cp "dist-native/$asset" "$pkgdir/bin/$bin"
+  chmod +x "$pkgdir/bin/$bin"
+  node scripts/gen-pkg.mjs platform "$pkgdir" "$VERSION" "$NPM_OS" "$NPM_CPU" "$bin"
+
+  PLATFORM_PKGS="$PLATFORM_PKGS @yoooclaw/cli-${NPM_OS}-${NPM_CPU}"
+done
+
+# 主 launcher 包
+maindir="dist-npm/cli"
+mkdir -p "$maindir/bin"
+cp npm/cli/bin/yc.js "$maindir/bin/yc.js"
+cp npm/cli/README.md "$maindir/README.md"
+node scripts/gen-pkg.mjs main "$maindir" "$VERSION" "$PLATFORM_PKGS"
+
+echo
+echo "完成 v${VERSION}："
+echo "  dist-native/  原始二进制"
+ls -1 dist-native | sed 's/^/    /'
+echo "  dist-npm/     npm 包（主包 + 平台子包）"
+ls -1 dist-npm | sed 's/^/    /'
diff --git a/scripts/gen-pkg.mjs b/scripts/gen-pkg.mjs
new file mode 100644
index 0000000..b6389af
--- /dev/null
+++ b/scripts/gen-pkg.mjs
@@ -0,0 +1,52 @@
+// 生成 npm 包的 package.json（主 launcher 包 / 各平台子包）。
+// 由 scripts/build-go.sh 调用；独立成文件以免在 shell 里手拼 JSON。
+//
+// 用法：
+//   node scripts/gen-pkg.mjs platform <dir> <version> <npmOs> <npmCpu> <binName>
+//   node scripts/gen-pkg.mjs main     <dir> <version> "<platformPkgName> ..."
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const [mode, dir, version, ...rest] = process.argv.slice(2);
+
+const COMMON = {
+  version,
+  license: "MIT",
+  author: "developer@yoooclaw.com",
+  repository: { type: "git", url: "https://github.com/YoooClaw/cli.git" },
+  publishConfig: { access: "public" },
+};
+
+function write(dir, pkg) {
+  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+}
+
+if (mode === "platform") {
+  const [npmOs, npmCpu, binName] = rest;
+  write(dir, {
+    name: `@yoooclaw/cli-${npmOs}-${npmCpu}`,
+    description: `yoooclaw CLI 原生二进制（${npmOs}-${npmCpu}）`,
+    ...COMMON,
+    // os/cpu 让 npm 只在匹配平台安装本子包；files 限定只发布二进制。
+    os: [npmOs],
+    cpu: [npmCpu],
+    files: [`bin/${binName}`],
+  });
+} else if (mode === "main") {
+  const deps = (rest[0] ?? "").trim().split(/\s+/).filter(Boolean);
+  const optionalDependencies = {};
+  for (const name of deps.sort()) optionalDependencies[name] = version;
+  write(dir, {
+    name: "@yoooclaw/cli",
+    description: "yoooclaw 独立 CLI（Go 实现，按平台分发原生二进制）",
+    ...COMMON,
+    bin: { yoooclaw: "bin/yc.js", yc: "bin/yc.js" },
+    files: ["bin/yc.js", "README.md"],
+    optionalDependencies,
+    engines: { node: ">=18" },
+    keywords: ["yoooclaw", "cli", "daemon", "notifications", "agent"],
+  });
+} else {
+  console.error(`gen-pkg: 未知 mode "${mode}"（应为 platform | main）`);
+  process.exit(1);
+}

From 9ab64aaee274a02d9afc63da5e9be383d337e490 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 16:41:26 +0800
Subject: [PATCH 02/13] =?UTF-8?q?feat(go):=20Phase=201=20read-only=20CLI?=
 =?UTF-8?q?=20=E2=80=94=20log/migrate/update/skills?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- internal/logread：daemon 日志检索（current + 轮转文件，最新行靠前）
- cmd_log：log [keyword] + +errors
- cmd_migrate：from-openclaw（dry-run 计划 + 目录递归复制 + api-key 迁移）
  fsutil.CopyDir / CountFiles
- cmd_update：update self（查 npm registry，按可执行路径推断 npm/native 升级命令）
  version.Dist() 运行期探测安装来源
- skills：go:embed 把 skills/ 整个嵌入二进制（assets.SkillsFS），
  install 解包复制到 agent 目录（claude/codex 探测）；list/targets/install 接线

至此 Phase 1 只读 CLI 命令面基本齐备（11 个 service）；image/recording 读侧
留待 Phase 2 与其存储模型一并落地。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 assets.go                   |  12 ++
 internal/cli/cmd_log.go     |  51 +++++++
 internal/cli/cmd_migrate.go | 147 ++++++++++++++++++++
 internal/cli/cmd_skills.go  |  84 +++++++++++
 internal/cli/cmd_update.go  | 139 +++++++++++++++++++
 internal/cli/root.go        |   4 +
 internal/fsutil/fsutil.go   |  51 +++++++
 internal/logread/logread.go | 119 ++++++++++++++++
 internal/skills/skills.go   | 268 ++++++++++++++++++++++++++++++++++++
 internal/version/version.go |  17 +++
 10 files changed, 892 insertions(+)
 create mode 100644 assets.go
 create mode 100644 internal/cli/cmd_log.go
 create mode 100644 internal/cli/cmd_migrate.go
 create mode 100644 internal/cli/cmd_skills.go
 create mode 100644 internal/cli/cmd_update.go
 create mode 100644 internal/logread/logread.go
 create mode 100644 internal/skills/skills.go

diff --git a/assets.go b/assets.go
new file mode 100644
index 0000000..cf4d4e9
--- /dev/null
+++ b/assets.go
@@ -0,0 +1,12 @@
+// Package assets 把随包发布的静态资源（SKILL.md 技能）通过 go:embed 编译进二进制。
+//
+// Go 重写后 CLI 是单一二进制，没有 TS 版那种 <pkg>/skills/ 同级目录可供解析与软链；
+// 因此把 skills/ 整个嵌入二进制，由 `skills install` 解包（复制）到 agent 技能目录。
+package assets
+
+import "embed"
+
+// SkillsFS 内嵌 skills/ 目录（含各 yoooclaw-*/SKILL.md）。
+//
+//go:embed all:skills
+var SkillsFS embed.FS
diff --git a/internal/cli/cmd_log.go b/internal/cli/cmd_log.go
new file mode 100644
index 0000000..56fb845
--- /dev/null
+++ b/internal/cli/cmd_log.go
@@ -0,0 +1,51 @@
+package cli
+
+import (
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/logread"
+	"github.com/spf13/cobra"
+)
+
+func newLogCmd() *cobra.Command {
+	c := &cobra.Command{
+		Use:   "log [keyword]",
+		Short: "日志检索 🟢",
+		Args:  cobra.MaximumNArgs(1),
+		RunE:  run(logSearch),
+	}
+	c.Flags().String("from", "", "YYYY-MM-DD，默认 7 天前")
+	c.Flags().String("to", "", "YYYY-MM-DD，默认今天")
+	c.Flags().String("limit", "50", "最大返回条数")
+	c.Flags().String("level", "", "过滤日志级别")
+
+	errorsCmd := &cobra.Command{Use: "+errors", Short: "昨天起的 error 级日志", Args: cobra.NoArgs, RunE: run(logErrors)}
+	c.AddCommand(errorsCmd)
+	return c
+}
+
+func logSearch(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	keyword := ""
+	if len(args) > 0 {
+		keyword = args[0]
+	}
+	from := flagStr(cmd, "from")
+	if from == "" {
+		from = localDaysAgo(7)
+	}
+	to := flagStr(cmd, "to")
+	if to == "" {
+		to = localToday()
+	}
+	lines := logread.Search(ctx.Paths.DaemonLog, logread.Query{
+		Keyword: keyword, Level: flagStr(cmd, "level"), From: from, To: to,
+		Limit: atoiDefault(flagStr(cmd, "limit"), 50),
+	})
+	return map[string]any{"ok": true, "keyword": nilIfEmpty(keyword), "total": len(lines), "lines": lines}, nil
+}
+
+func logErrors(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	lines := logread.Search(ctx.Paths.DaemonLog, logread.Query{
+		Level: "error", From: localDaysAgo(1), To: localToday(), Limit: 50,
+	})
+	return map[string]any{"ok": true, "level": "error", "total": len(lines), "lines": lines}, nil
+}
diff --git a/internal/cli/cmd_migrate.go b/internal/cli/cmd_migrate.go
new file mode 100644
index 0000000..3f3a870
--- /dev/null
+++ b/internal/cli/cmd_migrate.go
@@ -0,0 +1,147 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/paths"
+	"github.com/spf13/cobra"
+)
+
+// apiKeyField 是共享 credentials.json 里的 legacy api-key 字段名（与 creds 包一致）。
+const apiKeyField = "apiKey"
+
+func newMigrateCmd() *cobra.Command {
+	c := &cobra.Command{Use: "migrate", Short: "从 openclaw 插件迁移数据 🟢"}
+	fromOC := &cobra.Command{
+		Use:   "from-openclaw",
+		Short: "迁移 notifications/recordings/规则/api-key 到 ~/.yoooclaw",
+		Args:  cobra.NoArgs,
+		RunE:  run(migrateFromOpenclaw),
+	}
+	fromOC.Flags().Bool("dry-run", false, "只打印迁移计划，不写入")
+	fromOC.Flags().String("source", "", "自定义源目录，默认 ~/.openclaw")
+	c.AddCommand(fromOC)
+	return c
+}
+
+type subdirPlan struct {
+	Name      string `json:"name"`
+	Source    string `json:"source"`
+	Target    string `json:"target"`
+	Exists    bool   `json:"exists"`
+	FileCount int    `json:"fileCount"`
+}
+
+func migrateFromOpenclaw(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	sourceRoot := flagStr(cmd, "source")
+	if sourceRoot == "" {
+		home, _ := os.UserHomeDir()
+		sourceRoot = filepath.Join(home, ".openclaw")
+	}
+	pluginRoot := filepath.Join(sourceRoot, "plugins", "phone-notifications")
+
+	defs := []struct{ name, source, target string }{
+		{"notifications", filepath.Join(pluginRoot, "notifications"), ctx.Paths.Notifications},
+		{"recordings", filepath.Join(pluginRoot, "recordings"), ctx.Paths.Recordings},
+		{"light-rules", filepath.Join(pluginRoot, "light-rules"), ctx.Paths.LightRules},
+		{"images", filepath.Join(pluginRoot, "images"), ctx.Paths.Images},
+	}
+	plans := make([]subdirPlan, 0, len(defs))
+	for _, d := range defs {
+		plans = append(plans, subdirPlan{
+			Name: d.name, Source: d.source, Target: d.target,
+			Exists: fsutil.Exists(d.source), FileCount: fsutil.CountFiles(d.source),
+		})
+	}
+
+	// api-key 迁移计划。
+	var srcCreds map[string]any
+	_, _ = fsutil.ReadJSON(filepath.Join(sourceRoot, "credentials.json"), &srcCreds)
+	srcAPIKey, _ := srcCreds[apiKeyField].(string)
+	sharedPath := paths.SharedCredentialsPath()
+	var existingShared map[string]any
+	_, _ = fsutil.ReadJSON(sharedPath, &existingShared)
+	apiKeyAction := "none"
+	if srcAPIKey != "" {
+		if existingShared[apiKeyField] != nil {
+			apiKeyAction = "skip-existing"
+		} else {
+			apiKeyAction = "copy"
+		}
+	}
+
+	backupDir := ctx.Paths.Dir + ".bak-" + strconv.FormatInt(time.Now().UnixMilli(), 10)
+	willBackup := fsutil.Exists(ctx.Paths.Dir) && dirNonEmpty(ctx.Paths.Dir)
+
+	plansAny := make([]any, 0, len(plans))
+	for _, p := range plans {
+		plansAny = append(plansAny, map[string]any{
+			"name": p.Name, "source": p.Source, "target": p.Target, "exists": p.Exists, "fileCount": p.FileCount,
+		})
+	}
+
+	if flagBool(cmd, "dry-run") {
+		return map[string]any{
+			"ok": true, "dryRun": true, "source": sourceRoot, "profile": ctx.Profile,
+			"backup": backupOrNil(willBackup, backupDir), "subdirs": plansAny,
+			"apiKey": map[string]any{"action": apiKeyAction},
+			"hint":   "迁移前请先停止 openclaw 客户端，避免插件还在写 notifications 导致数据竞争",
+		}, nil
+	}
+
+	if willBackup {
+		if err := fsutil.CopyDir(ctx.Paths.Dir, backupDir); err != nil {
+			return nil, err
+		}
+	}
+	if err := fsutil.EnsureDir(ctx.Paths.Dir, fsutil.DirMode); err != nil {
+		return nil, err
+	}
+
+	migrated := []string{}
+	for _, p := range plans {
+		if !p.Exists {
+			continue
+		}
+		if err := fsutil.CopyDir(p.Source, p.Target); err != nil {
+			return nil, err
+		}
+		migrated = append(migrated, p.Name)
+	}
+
+	apiKeyResult := apiKeyAction
+	if apiKeyAction == "copy" && srcAPIKey != "" {
+		data := existingShared
+		if data == nil {
+			data = map[string]any{}
+		}
+		data[apiKeyField] = srcAPIKey
+		if err := fsutil.WriteJSON(sharedPath, data, fsutil.SecretFileMode); err != nil {
+			return nil, err
+		}
+		apiKeyResult = "copied"
+	}
+
+	return map[string]any{
+		"ok": true, "source": sourceRoot, "profile": ctx.Profile,
+		"backup": backupOrNil(willBackup, backupDir), "migrated": migrated,
+		"apiKey": map[string]any{"action": apiKeyResult},
+	}, nil
+}
+
+func dirNonEmpty(dir string) bool {
+	entries, err := os.ReadDir(dir)
+	return err == nil && len(entries) > 0
+}
+
+func backupOrNil(willBackup bool, dir string) any {
+	if willBackup {
+		return dir
+	}
+	return nil
+}
diff --git a/internal/cli/cmd_skills.go b/internal/cli/cmd_skills.go
new file mode 100644
index 0000000..1ac073a
--- /dev/null
+++ b/internal/cli/cmd_skills.go
@@ -0,0 +1,84 @@
+package cli
+
+import (
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/skills"
+	"github.com/spf13/cobra"
+)
+
+func newSkillsCmd() *cobra.Command {
+	c := &cobra.Command{Use: "skills", Short: "Agent 技能管理：把随包发布的 SKILL.md 装到 agent 可发现目录 🟢"}
+
+	listCmd := &cobra.Command{Use: "list", Short: "列出随 CLI 发布的内置 Skill 及其触发说明", Args: cobra.NoArgs, RunE: run(skillsList)}
+	targetsCmd := &cobra.Command{Use: "targets", Short: "列出支持的 Agent skills 目录与自动探测结果", Args: cobra.NoArgs, RunE: run(skillsTargets)}
+	installCmd := &cobra.Command{Use: "install", Short: "把内置 Skill 安装到 agent skills 目录（默认自动探测）", Args: cobra.NoArgs, RunE: run(skillsInstall)}
+	installCmd.Flags().String("agent", "auto", "安装目标 agent：auto|claude|codex|custom")
+	installCmd.Flags().String("target", "", "安装目标目录；传入后优先于自动探测")
+	installCmd.Flags().Bool("copy", false, "复制（内嵌资源恒为复制，本 flag 仅兼容）")
+	installCmd.Flags().Bool("force", false, "目标已存在同名 Skill 时覆盖")
+
+	c.AddCommand(listCmd, targetsCmd, installCmd)
+	return c
+}
+
+func skillsList(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	list, err := skills.List()
+	if err != nil {
+		return nil, err
+	}
+	items := make([]any, 0, len(list))
+	for _, s := range list {
+		items = append(items, map[string]any{"name": s.Name, "title": s.Title, "description": s.Description})
+	}
+	return map[string]any{
+		"ok": true, "count": len(list), "skills": items,
+		"hint": "用 `yoooclaw skills targets` 查看可安装目标，再用 `yoooclaw skills install --agent <agent>` 安装",
+	}, nil
+}
+
+func skillsTargets(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	targets := skills.Targets()
+	items := make([]any, 0, len(targets))
+	for _, t := range targets {
+		items = append(items, map[string]any{
+			"agent": t.Agent, "label": t.Label, "homeDir": t.HomeDir, "target": t.Target,
+			"detected": t.Detected, "reason": t.Reason, "installCommand": t.InstallCommand,
+		})
+	}
+	return map[string]any{
+		"ok": true, "targets": items,
+		"hint": "裸 `yoooclaw skills install` 只会在检测到唯一 Agent 时自动安装；否则请显式传 `--agent` 或 `--target`",
+	}, nil
+}
+
+func skillsInstall(_ *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	sel, err := skills.ResolveTarget(flagStr(cmd, "agent"), flagStr(cmd, "target"))
+	if err != nil {
+		return nil, err
+	}
+	results, installed, err := skills.Install(sel.Target, flagBool(cmd, "force"))
+	if err != nil {
+		return nil, err
+	}
+	resultsAny := make([]any, 0, len(results))
+	skipped := make([]any, 0)
+	for _, r := range results {
+		m := map[string]any{"name": r.Name, "status": r.Status, "dest": r.Dest}
+		if r.Reason != "" {
+			m["reason"] = r.Reason
+		}
+		resultsAny = append(resultsAny, m)
+		if r.Status == "skipped" {
+			skipped = append(skipped, m)
+		}
+	}
+	hint := "没有新安装的 Skill（已存在则加 --force 覆盖）"
+	if len(installed) > 0 {
+		hint = "重启 agent 会话后即可被发现；升级 CLI 后请重跑本命令刷新"
+	}
+	return map[string]any{
+		"ok": true, "agent": sel.Agent, "agentLabel": sel.AgentLabel, "target": sel.Target,
+		"targetSource": sel.Source, "mode": "copy", "installed": installed,
+		"skipped": skipped, "results": resultsAny, "hint": hint,
+	}, nil
+}
diff --git a/internal/cli/cmd_update.go b/internal/cli/cmd_update.go
new file mode 100644
index 0000000..f66acee
--- /dev/null
+++ b/internal/cli/cmd_update.go
@@ -0,0 +1,139 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/version"
+	"github.com/spf13/cobra"
+)
+
+const (
+	updatePackage   = "@yoooclaw/cli"
+	updateRegistry  = "https://registry.npmjs.org"
+	updateInstallSh = "https://raw.githubusercontent.com/YoooClaw/cli/master/scripts/install.sh"
+)
+
+func newUpdateCmd() *cobra.Command {
+	c := &cobra.Command{Use: "update", Short: "版本检查 🟢"}
+	self := &cobra.Command{Use: "self", Short: "检查 npm 最新版本并提示（不自动更新）", Args: cobra.NoArgs, RunE: run(updateSelf)}
+	self.Flags().Bool("beta", false, "检查 beta channel")
+	self.Flags().Bool("json", false, "只输出版本信息 JSON")
+	c.AddCommand(self)
+	return c
+}
+
+func nativeTargetName() string {
+	os, arch := runtime.GOOS, runtime.GOARCH
+	if arch == "amd64" {
+		arch = "x64"
+	}
+	if (os == "darwin" || os == "linux") && (arch == "arm64" || arch == "x64") {
+		return "yoooclaw-" + os + "-" + arch
+	}
+	return ""
+}
+
+func upgradeCommand(channel, latest string) string {
+	if version.Dist() == "native" {
+		if nativeTargetName() == "" {
+			return "curl -fsSL " + updateInstallSh + " | sh"
+		}
+		return "curl -fsSL " + updateInstallSh + " | sh -s -- --version " + latest
+	}
+	if channel == "beta" {
+		return "npm i -g " + updatePackage + "@beta"
+	}
+	return "npm update -g " + updatePackage
+}
+
+// compareSemver 比较 x.y.z（忽略 prerelease）；a>b 返回 1，a<b 返回 -1，相等 0。
+func compareSemver(a, b string) int {
+	pa := semverParts(a)
+	pb := semverParts(b)
+	for i := 0; i < 3; i++ {
+		if d := pa[i] - pb[i]; d != 0 {
+			if d > 0 {
+				return 1
+			}
+			return -1
+		}
+	}
+	return 0
+}
+
+func semverParts(v string) [3]int {
+	core := strings.SplitN(v, "-", 2)[0]
+	var out [3]int
+	for i, seg := range strings.SplitN(core, ".", 3) {
+		if i > 2 {
+			break
+		}
+		n, _ := strconv.Atoi(seg)
+		out[i] = n
+	}
+	return out
+}
+
+func updateSelf(_ *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	tag := "latest"
+	if flagBool(cmd, "beta") {
+		tag = "beta"
+	}
+	ctxReq, cancel := context.WithTimeout(context.Background(), 8*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctxReq, http.MethodGet, updateRegistry+"/"+url(updatePackage), nil)
+	if err != nil {
+		return nil, errs.New(errs.CodeNetworkError, "构造 npm 请求失败")
+	}
+	req.Header.Set("Accept", "application/vnd.npm.install-v1+json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, errs.New(errs.CodeNetworkError, "查询 npm registry 失败："+err.Error())
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, errs.New(errs.CodeNetworkError, "npm registry 返回 "+strconv.Itoa(resp.StatusCode))
+	}
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, errs.New(errs.CodeNetworkError, "读取 npm registry 响应失败")
+	}
+	var parsed struct {
+		DistTags map[string]string `json:"dist-tags"`
+	}
+	if err := json.Unmarshal(body, &parsed); err != nil {
+		return nil, errs.New(errs.CodeNetworkError, "解析 npm registry 响应失败")
+	}
+	latest, ok := parsed.DistTags[tag]
+	if !ok || latest == "" {
+		return nil, errs.New(errs.CodeNotFound, "npm dist-tag `"+tag+"` 不存在")
+	}
+
+	updateAvailable := compareSemver(latest, version.Version) > 0
+	var command any
+	hint := "已是最新版本"
+	if updateAvailable {
+		command = upgradeCommand(tag, latest)
+		hint = "发现新版本；CLI 不做自动更新，请手动执行上面的命令"
+	}
+	return map[string]any{
+		"ok": true, "package": updatePackage, "channel": tag, "dist": version.Dist(),
+		"current": version.Version, "latest": latest, "updateAvailable": updateAvailable,
+		"command": command, "hint": hint,
+	}, nil
+}
+
+// url 对 @scope/name 做最简 path 编码（@ 与 / 需转义）。
+func url(pkg string) string {
+	return strings.ReplaceAll(pkg, "/", "%2F")
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 5920843..152e5e3 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -31,6 +31,10 @@ func newRootCmd() *cobra.Command {
 		newProfileCmd(),
 		newAuthCmd(),
 		newNotificationCmd(),
+		newLogCmd(),
+		newMigrateCmd(),
+		newUpdateCmd(),
+		newSkillsCmd(),
 		newDoctorCmd(),
 	)
 	return root
diff --git a/internal/fsutil/fsutil.go b/internal/fsutil/fsutil.go
index 80adfda..f4dbccf 100644
--- a/internal/fsutil/fsutil.go
+++ b/internal/fsutil/fsutil.go
@@ -93,3 +93,54 @@ func Exists(path string) bool {
 	_, err := os.Stat(path)
 	return err == nil
 }
+
+// CopyDir 递归复制 src 到 dst（保留文件权限位）。
+func CopyDir(src, dst string) error {
+	return filepath.WalkDir(src, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+		target := filepath.Join(dst, rel)
+		if d.IsDir() {
+			return os.MkdirAll(target, DirMode)
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		if info.Mode()&os.ModeSymlink != 0 {
+			link, err := os.Readlink(path)
+			if err != nil {
+				return err
+			}
+			return os.Symlink(link, target)
+		}
+		data, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		if err := os.MkdirAll(filepath.Dir(target), DirMode); err != nil {
+			return err
+		}
+		return os.WriteFile(target, data, info.Mode().Perm())
+	})
+}
+
+// CountFiles 递归统计 dir 下的条目数（含目录，对齐 TS readdirSync recursive 语义）。
+func CountFiles(dir string) int {
+	count := 0
+	_ = filepath.WalkDir(dir, func(path string, _ os.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if path != dir {
+			count++
+		}
+		return nil
+	})
+	return count
+}
diff --git a/internal/logread/logread.go b/internal/logread/logread.go
new file mode 100644
index 0000000..05d8e74
--- /dev/null
+++ b/internal/logread/logread.go
@@ -0,0 +1,119 @@
+// Package logread 读取 daemon 日志（daemon.log + 轮转文件 daemon.log.YYYY-MM-DD）。
+//
+// 行格式（与 daemon logger 写入一致）：`<ISO时间> [LEVEL] message`。
+package logread
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Line 是一条解析后的日志行。
+type Line struct {
+	Date    string `json:"date"`
+	Level   string `json:"level"`
+	Time    string `json:"time"`
+	Message string `json:"message"`
+	Raw     string `json:"raw"`
+}
+
+// Query 是日志检索条件。
+type Query struct {
+	Keyword string
+	Level   string
+	From    string
+	To      string
+	Limit   int
+}
+
+var lineRE = regexp.MustCompile(`^(\d{4}-\d{2}-\d{2})(T\S+)?\s+\[(\w+)\]\s+(.*)$`)
+var rotatedRE = regexp.MustCompile(`\.\d{4}-\d{2}-\d{2}$`)
+
+// logFiles 收集 current + 轮转日志路径（current 在最前，轮转按日期倒序）。
+func logFiles(daemonLog string) []string {
+	dir := filepath.Dir(daemonLog)
+	base := filepath.Base(daemonLog)
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+	var rotated []string
+	for _, e := range entries {
+		name := e.Name()
+		if strings.HasPrefix(name, base+".") && rotatedRE.MatchString(name) {
+			rotated = append(rotated, filepath.Join(dir, name))
+		}
+	}
+	sort.Sort(sort.Reverse(sort.StringSlice(rotated)))
+	var files []string
+	if _, err := os.Stat(daemonLog); err == nil {
+		files = append(files, daemonLog)
+	}
+	return append(files, rotated...)
+}
+
+func parseLine(raw string) *Line {
+	m := lineRE.FindStringSubmatch(raw)
+	if m == nil {
+		return nil
+	}
+	return &Line{Date: m[1], Time: m[1] + m[2], Level: strings.ToLower(m[3]), Message: m[4], Raw: raw}
+}
+
+// Search 检索日志，最新行靠前，受 limit 截断。
+func Search(daemonLog string, q Query) []Line {
+	keyword := strings.ToLower(q.Keyword)
+	level := strings.ToLower(q.Level)
+	var results []Line
+
+	for _, file := range logFiles(daemonLog) {
+		content, err := os.ReadFile(file)
+		if err != nil {
+			continue
+		}
+		lines := nonEmptyLines(string(content))
+		// 单文件内反转使最新行靠前。
+		for i := len(lines) - 1; i >= 0; i-- {
+			if len(results) >= q.Limit {
+				return results
+			}
+			raw := lines[i]
+			parsed := parseLine(raw)
+			date := ""
+			if parsed != nil {
+				date = parsed.Date
+			}
+			if q.From != "" && date != "" && date < q.From {
+				continue
+			}
+			if q.To != "" && date != "" && date > q.To {
+				continue
+			}
+			if level != "" && parsed != nil && parsed.Level != level {
+				continue
+			}
+			if keyword != "" && !strings.Contains(strings.ToLower(raw), keyword) {
+				continue
+			}
+			if parsed != nil {
+				results = append(results, *parsed)
+			} else {
+				results = append(results, Line{Message: raw, Raw: raw})
+			}
+		}
+	}
+	return results
+}
+
+func nonEmptyLines(content string) []string {
+	var out []string
+	for _, l := range strings.Split(content, "\n") {
+		if l != "" {
+			out = append(out, l)
+		}
+	}
+	return out
+}
diff --git a/internal/skills/skills.go b/internal/skills/skills.go
new file mode 100644
index 0000000..732ba9c
--- /dev/null
+++ b/internal/skills/skills.go
@@ -0,0 +1,268 @@
+// Package skills 列出并安装随二进制内嵌的 SKILL.md 到 agent 可发现目录
+// （对齐 TS 版 src/commands/skills.ts，但来源从 <pkg>/skills/ 改为内嵌 FS）。
+package skills
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	assets "github.com/YoooClaw/cli"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+const embedRoot = "skills"
+
+// Bundled 是一个内嵌 Skill 的元数据。
+type Bundled struct {
+	Name        string `json:"name"`
+	Title       string `json:"title"`
+	Description string `json:"description"`
+}
+
+var fmBlockRE = regexp.MustCompile(`(?s)^---\r?\n(.*?)\r?\n---`)
+
+func pickMeta(block, key string) string {
+	re := regexp.MustCompile(`(?m)^` + regexp.QuoteMeta(key) + `:\s*(.+)$`)
+	if m := re.FindStringSubmatch(block); m != nil {
+		return strings.TrimSpace(m[1])
+	}
+	return ""
+}
+
+func parseSkillMeta(md string) (name, description string) {
+	block := md
+	if m := fmBlockRE.FindStringSubmatch(md); m != nil {
+		block = m[1]
+	}
+	return pickMeta(block, "name"), pickMeta(block, "description")
+}
+
+// List 列出所有内嵌 Skill（含 frontmatter 元数据），按名排序。
+func List() ([]Bundled, error) {
+	entries, err := fs.ReadDir(assets.SkillsFS, embedRoot)
+	if err != nil {
+		return nil, errs.New(errs.CodeNotFound, "找不到内嵌的 skills 资源")
+	}
+	var out []Bundled
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		mdPath := embedRoot + "/" + e.Name() + "/SKILL.md"
+		raw, err := fs.ReadFile(assets.SkillsFS, mdPath)
+		if err != nil {
+			continue
+		}
+		name, desc := parseSkillMeta(string(raw))
+		title := name
+		if title == "" {
+			title = e.Name()
+		}
+		out = append(out, Bundled{Name: e.Name(), Title: title, Description: desc})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, nil
+}
+
+// TargetCandidate 是一个可安装目标 agent。
+type TargetCandidate struct {
+	Agent          string `json:"agent"`
+	Label          string `json:"label"`
+	HomeDir        string `json:"homeDir"`
+	Target         string `json:"target"`
+	Detected       bool   `json:"detected"`
+	Reason         string `json:"reason"`
+	InstallCommand string `json:"installCommand"`
+}
+
+func claudeHome() string {
+	h, _ := os.UserHomeDir()
+	return filepath.Join(h, ".claude")
+}
+
+func codexHome() string {
+	if v := strings.TrimSpace(os.Getenv("CODEX_HOME")); v != "" {
+		return v
+	}
+	h, _ := os.UserHomeDir()
+	return filepath.Join(h, ".codex")
+}
+
+type adapter struct {
+	id, label, envHint string
+	home               func() string
+}
+
+var adapters = []adapter{
+	{id: "claude", label: "Claude Code", home: claudeHome},
+	{id: "codex", label: "Codex", envHint: "CODEX_HOME", home: codexHome},
+}
+
+func adapterByID(id string) *adapter {
+	for i := range adapters {
+		if adapters[i].id == id {
+			return &adapters[i]
+		}
+	}
+	return nil
+}
+
+// Targets 列出 agent 候选目标及自动探测结果。
+func Targets() []TargetCandidate {
+	out := make([]TargetCandidate, 0, len(adapters))
+	for _, a := range adapters {
+		home := a.home()
+		target := filepath.Join(home, "skills")
+		hasHome := fsutil.Exists(home)
+		hasTarget := fsutil.Exists(target)
+		envVal := ""
+		if a.envHint != "" {
+			envVal = strings.TrimSpace(os.Getenv(a.envHint))
+		}
+		reason := "未发现配置目录；可显式传 --agent " + a.id
+		switch {
+		case hasTarget:
+			reason = "skills 目录已存在"
+		case hasHome:
+			reason = "agent 配置目录已存在"
+		case envVal != "" && a.envHint != "":
+			reason = a.envHint + " 已设置"
+		case a.envHint != "":
+			reason = "未发现配置目录；可设置 " + a.envHint + " 或显式传 --agent " + a.id
+		}
+		out = append(out, TargetCandidate{
+			Agent: a.id, Label: a.label, HomeDir: home, Target: target,
+			Detected: hasHome || hasTarget || envVal != "", Reason: reason,
+			InstallCommand: "yoooclaw skills install --agent " + a.id,
+		})
+	}
+	return out
+}
+
+// Selection 是解析后的安装目标。
+type Selection struct {
+	Agent      string
+	AgentLabel string
+	Target     string
+	Source     string
+	Detected   []TargetCandidate
+}
+
+// ResolveTarget 解析安装目标（对齐 TS resolveTargetSelection）。
+func ResolveTarget(agentRaw, targetRaw string) (Selection, error) {
+	agent := strings.TrimSpace(agentRaw)
+	if agent == "" {
+		agent = "auto"
+	}
+	valid := map[string]bool{"auto": true, "custom": true, "claude": true, "codex": true}
+	if !valid[agent] {
+		return Selection{}, errs.New(errs.CodeInvalidArgument, "不支持的 agent："+agent).
+			WithHint("可选值：auto | custom | claude | codex")
+	}
+	explicit := strings.TrimSpace(targetRaw)
+	if explicit != "" {
+		if agent == "auto" || agent == "custom" {
+			return Selection{Agent: "custom", AgentLabel: "Custom", Target: explicit, Source: "explicit-target"}, nil
+		}
+		a := adapterByID(agent)
+		return Selection{Agent: agent, AgentLabel: a.label, Target: explicit, Source: "explicit-target"}, nil
+	}
+	if agent == "custom" {
+		return Selection{}, errs.New(errs.CodeInvalidArgument, "`--agent custom` 需要同时传 `--target <dir>`").
+			WithHint("例如：yoooclaw skills install --agent custom --target ~/.config/agent/skills")
+	}
+	if agent != "auto" {
+		a := adapterByID(agent)
+		return Selection{Agent: agent, AgentLabel: a.label, Target: filepath.Join(a.home(), "skills"), Source: "agent-default"}, nil
+	}
+	candidates := Targets()
+	var detected []TargetCandidate
+	for _, c := range candidates {
+		if c.Detected {
+			detected = append(detected, c)
+		}
+	}
+	if len(detected) == 1 {
+		only := detected[0]
+		return Selection{Agent: only.Agent, AgentLabel: only.Label, Target: only.Target, Source: "auto-detected", Detected: detected}, nil
+	}
+	if len(detected) == 0 {
+		return Selection{}, errs.New(errs.CodeNotFound, "未检测到可安装 Skill 的 Agent",
+			map[string]any{"hint": "请显式指定 `--agent claude` / `--agent codex`，或使用 `--target <dir>`"})
+	}
+	return Selection{}, errs.New(errs.CodeConfirmationRequired, "检测到多个 Agent，无法自动判断 Skill 应安装到哪里",
+		map[string]any{"hint": "请显式指定 `--agent claude` / `--agent codex`，或使用 `--target <dir>`"})
+}
+
+// InstallResult 是单个 Skill 的安装结果。
+type InstallResult struct {
+	Name   string `json:"name"`
+	Status string `json:"status"` // installed | skipped
+	Reason string `json:"reason,omitempty"`
+	Dest   string `json:"dest"`
+}
+
+// Install 把内嵌 Skill 复制到 target；force 时覆盖已存在目录。
+//
+// 与 TS 版不同：内嵌资源无法软链回源，故一律复制；升级 CLI 后需重跑本命令刷新。
+func Install(target string, force bool) ([]InstallResult, []string, error) {
+	skills, err := List()
+	if err != nil {
+		return nil, nil, err
+	}
+	if err := fsutil.EnsureDir(target, fsutil.DirMode); err != nil {
+		return nil, nil, err
+	}
+	var results []InstallResult
+	var installed []string
+	for _, s := range skills {
+		dest := filepath.Join(target, s.Name)
+		if fsutil.Exists(dest) {
+			if !force {
+				results = append(results, InstallResult{Name: s.Name, Status: "skipped", Reason: "目标已存在，加 --force 覆盖", Dest: dest})
+				continue
+			}
+			if err := os.RemoveAll(dest); err != nil {
+				return nil, nil, err
+			}
+		}
+		if err := extractSkill(s.Name, dest); err != nil {
+			return nil, nil, err
+		}
+		results = append(results, InstallResult{Name: s.Name, Status: "installed", Dest: dest})
+		installed = append(installed, s.Name)
+	}
+	return results, installed, nil
+}
+
+// extractSkill 把内嵌的 skills/<name>/** 写到 dest。
+func extractSkill(name, dest string) error {
+	srcRoot := embedRoot + "/" + name
+	return fs.WalkDir(assets.SkillsFS, srcRoot, func(p string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel := strings.TrimPrefix(p, srcRoot)
+		rel = strings.TrimPrefix(rel, "/")
+		outPath := dest
+		if rel != "" {
+			outPath = filepath.Join(dest, filepath.FromSlash(rel))
+		}
+		if d.IsDir() {
+			return fsutil.EnsureDir(outPath, fsutil.DirMode)
+		}
+		data, err := fs.ReadFile(assets.SkillsFS, p)
+		if err != nil {
+			return err
+		}
+		if err := fsutil.EnsureDir(filepath.Dir(outPath), fsutil.DirMode); err != nil {
+			return err
+		}
+		return os.WriteFile(outPath, data, fsutil.ConfigFileMode)
+	})
+}
diff --git a/internal/version/version.go b/internal/version/version.go
index 763b181..3818153 100644
--- a/internal/version/version.go
+++ b/internal/version/version.go
@@ -7,5 +7,22 @@
 // 本地直接 go run/build 时回退为 "dev"。
 package version
 
+import (
+	"os"
+	"strings"
+)
+
 // Version 是 CLI 版本号；构建期注入，默认 "dev"。
 var Version = "dev"
+
+// Dist 推断安装来源（"npm" / "native"）。
+//
+// Go 重写后同一份二进制既走 npm 平台子包也走 GitHub Release，无法在构建期固定区分，
+// 因此运行期按可执行文件路径是否在 node_modules 下来判定，决定 update 的升级命令。
+func Dist() string {
+	exe, err := os.Executable()
+	if err == nil && strings.Contains(exe, "node_modules") {
+		return "npm"
+	}
+	return "native"
+}

From 65fb9974250613d3bc51f3c2fef6945057e46c63 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 16:49:23 +0800
Subject: [PATCH 03/13] =?UTF-8?q?feat(go):=20Phase=202=20=E2=80=94=20daemo?=
 =?UTF-8?q?n=20HTTP=20server=20+=20=E9=80=9A=E7=9F=A5=20ingest=20=E5=86=99?=
 =?UTF-8?q?=E4=BE=A7=EF=BC=88standalone=20HTTP=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLI 现在能跑起 daemon 并经 HTTP 接收手机通知，打通 ingest→存储→查询全链路。

- notif 写侧：NewStorage ingest（id 去重 + content-key sha256 去重 + 飞书归一化
  feishu.go + retentionDays 过期清理），sync.Mutex 串行化写入
- daemon/logger：按日期轮转的文件 logger（行格式对齐 logread）
- daemon/lock：WriteLock/RemoveLock；proc_unix/windows 增 detach attr + terminate/forceKill
- daemon/server：前台主循环 + 端口占用自动 +1；路由 /health、/daemon/status|stop|reload、
  POST /notifications、/gateway/notifications.push；鉴权（gateway-token / http-api-key / local）
- daemon/spawn：fork 脱离会话子进程跑 run-foreground，轮询 lock；Stop 走 SIGTERM/端点 + 10s 强杀
- daemon/client：CLI↔daemon HTTP RPC，连接被拒报 DAEMON_NOT_RUNNING
- cli：daemon start/stop/restart/reload/status/logs/run-foreground 接线；
  config init 自动拉起 daemon；auth check 走 daemon /daemon/status

端到端验证：daemon start（detach，端口回退）→ POST 通知 ingest=1 → 重复 POST dedupedById=1
→ notification search 命中 → daemon stop（SIGTERM 优雅退出）→ status 报未运行 exit1。

Relay 隧道与 recordings/images/light/monitor 留待 Phase 3 / 后续。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/cli/cmd_auth.go        |  15 +-
 internal/cli/cmd_config.go      |  37 +++-
 internal/cli/cmd_daemon.go      | 184 +++++++++++++++++
 internal/cli/root.go            |   1 +
 internal/daemon/client.go       |  98 +++++++++
 internal/daemon/lock.go         |  15 ++
 internal/daemon/logger.go       |  97 +++++++++
 internal/daemon/proc_unix.go    |  11 +
 internal/daemon/proc_windows.go |  21 +-
 internal/daemon/server.go       | 349 +++++++++++++++++++++++++++++++
 internal/daemon/spawn.go        |  77 +++++++
 internal/notif/feishu.go        | 154 ++++++++++++++
 internal/notif/storage.go       | 352 ++++++++++++++++++++++++++++++++
 13 files changed, 1402 insertions(+), 9 deletions(-)
 create mode 100644 internal/cli/cmd_daemon.go
 create mode 100644 internal/daemon/client.go
 create mode 100644 internal/daemon/logger.go
 create mode 100644 internal/daemon/server.go
 create mode 100644 internal/daemon/spawn.go
 create mode 100644 internal/notif/feishu.go
 create mode 100644 internal/notif/storage.go

diff --git a/internal/cli/cmd_auth.go b/internal/cli/cmd_auth.go
index 8e4880a..85ae11f 100644
--- a/internal/cli/cmd_auth.go
+++ b/internal/cli/cmd_auth.go
@@ -212,7 +212,16 @@ func authTokenRotate(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any,
 	return map[string]any{"ok": true, "token": token, "source": written.Source, "location": written.Location, "hint": hot}, nil
 }
 
-func authCheck(_ *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
-	// 端到端体检需要 daemon HTTP client，Phase 2 接入。
-	return nil, errs.NotImplemented("auth check")
+func authCheck(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	if err := daemon.AssertRunning(ctx.Paths); err != nil {
+		return nil, err
+	}
+	status, body, err := daemon.NewClient(ctx.Paths).Request("GET", "/daemon/status", nil)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"ok": status >= 200 && status < 300, "profile": ctx.Profile,
+		"daemonReachable": true, "status": status, "daemon": body,
+	}, nil
 }
diff --git a/internal/cli/cmd_config.go b/internal/cli/cmd_config.go
index 26b3adb..68eedfd 100644
--- a/internal/cli/cmd_config.go
+++ b/internal/cli/cmd_config.go
@@ -7,12 +7,38 @@ import (
 	"github.com/YoooClaw/cli/internal/clictx"
 	"github.com/YoooClaw/cli/internal/config"
 	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/daemon"
 	"github.com/YoooClaw/cli/internal/errs"
 	"github.com/YoooClaw/cli/internal/fsutil"
 	"github.com/YoooClaw/cli/internal/prompt"
 	"github.com/spf13/cobra"
 )
 
+// startDaemonForInit 在 init 收尾拉起 daemon；失败/已在运行都不阻断 init。
+func startDaemonForInit(ctx *clictx.Context) map[string]any {
+	if st := daemon.State(ctx.Paths); st.Running {
+		return map[string]any{"started": true, "alreadyRunning": true, "pid": st.Lock.PID}
+	}
+	lock, err := daemon.Spawn(ctx, daemon.StartOpts{})
+	if err != nil {
+		return map[string]any{"started": false, "error": err.Error()}
+	}
+	return map[string]any{"started": true, "pid": lock.PID}
+}
+
+func initHint(started, apiKeyPresent bool) string {
+	if !started {
+		if apiKeyPresent {
+			return "配置已就绪：运行 yc daemon start 启动 daemon"
+		}
+		return "配置已就绪：运行 yc auth set-api-key <ock_…> 设置 api-key，再 yc daemon start"
+	}
+	if apiKeyPresent {
+		return "已就绪：daemon 已启动；手机 App 绑定同一账号即可收发（Relay 隧道 Phase 3 接入）"
+	}
+	return "daemon 已启动，但尚未设置 api-key：运行 yc auth set-api-key <ock_…> 后 yc daemon restart"
+}
+
 func newConfigCmd() *cobra.Command {
 	c := &cobra.Command{Use: "config", Short: "配置管理 🟢"}
 
@@ -117,13 +143,14 @@ func initCore(ctx *clictx.Context, o initOpts) (any, error) {
 		return nil, err
 	}
 
-	// daemon 自动拉起在 Phase 2 接入；此处只生成配置并报告未启动。
+	// init 即用：默认把 daemon 拉起来；--no-start 跳过。失败不阻断 init（配置已落盘）。
 	apiKey := creds.ResolveAPIKey()
-	daemonInfo := map[string]any{"started": false, "note": "daemon 自动启动将在 Phase 2 接入；当前可手动 yc daemon start（Phase 2）"}
-	hint := "配置已就绪：Phase 2 接入 daemon 后即可 yc daemon start 并连上 Relay"
-	if apiKey.Value == "" {
-		hint = "配置已就绪：运行 yc auth set-api-key <ock_…> 设置 Relay api-key"
+	daemonInfo := map[string]any{"started": false}
+	if !o.noStart {
+		daemonInfo = startDaemonForInit(ctx)
 	}
+	started, _ := daemonInfo["started"].(bool)
+	hint := initHint(started, apiKey.Value != "")
 	return map[string]any{
 		"ok":      true,
 		"profile": ctx.Profile,
diff --git a/internal/cli/cmd_daemon.go b/internal/cli/cmd_daemon.go
new file mode 100644
index 0000000..395a2c7
--- /dev/null
+++ b/internal/cli/cmd_daemon.go
@@ -0,0 +1,184 @@
+package cli
+
+import (
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/daemon"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/spf13/cobra"
+)
+
+func newDaemonCmd() *cobra.Command {
+	c := &cobra.Command{Use: "daemon", Short: "守护进程管理 🔵"}
+
+	start := &cobra.Command{Use: "start", Short: "启动 daemon（默认后台 detach）", Args: cobra.NoArgs, RunE: run(daemonStart)}
+	start.Flags().String("bind", "", "监听地址（默认 config.daemon.bind）")
+	start.Flags().String("port", "", "监听端口（默认 config.daemon.port）")
+	start.Flags().Bool("no-detach", false, "前台运行（systemd/launchd 用）")
+	start.Flags().String("log-level", "", "error|warn|info|debug|trace")
+
+	stop := &cobra.Command{Use: "stop", Short: "停止 daemon（SIGTERM → 10s → SIGKILL）", Args: cobra.NoArgs, RunE: run(daemonStop)}
+	restart := &cobra.Command{Use: "restart", Short: "stop + start，保留原启动参数", Args: cobra.NoArgs, RunE: run(daemonRestart)}
+	restart.Flags().String("bind", "", "监听地址")
+	restart.Flags().String("port", "", "监听端口")
+	restart.Flags().Bool("no-detach", false, "前台运行")
+	restart.Flags().String("log-level", "", "日志级别")
+	reload := &cobra.Command{Use: "reload", Short: "重读凭据并增量刷新 Relay 隧道", Args: cobra.NoArgs, RunE: run(daemonReload)}
+	status := &cobra.Command{Use: "status", Short: "打印 daemon 状态（PID/端口/relay/规则数...）", Args: cobra.NoArgs, RunE: run(daemonStatus)}
+
+	logs := &cobra.Command{Use: "logs", Short: "跟踪 daemon 日志", Args: cobra.NoArgs, RunE: run(daemonLogs)}
+	logs.Flags().BoolP("follow", "f", false, "持续 tail")
+	logs.Flags().String("lines", "100", "初始展示行数")
+	logs.Flags().String("level", "", "过滤日志级别")
+
+	runFg := &cobra.Command{Use: "run-foreground", Short: "（内部）前台运行 daemon 主循环", Args: cobra.NoArgs, RunE: run(daemonRunForeground)}
+	runFg.Flags().String("bind", "", "监听地址")
+	runFg.Flags().String("port", "", "监听端口")
+	runFg.Flags().String("log-level", "", "日志级别")
+
+	c.AddCommand(start, stop, restart, reload, status, logs, runFg)
+	return c
+}
+
+func startOptsFromCmd(cmd *cobra.Command) daemon.StartOpts {
+	port := 0
+	if s := flagStr(cmd, "port"); s != "" {
+		port, _ = strconv.Atoi(s)
+	}
+	return daemon.StartOpts{Bind: flagStr(cmd, "bind"), Port: port, LogLevel: flagStr(cmd, "log-level")}
+}
+
+func daemonRunForeground(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	if err := daemon.RunForeground(ctx, startOptsFromCmd(cmd)); err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": true}, nil
+}
+
+func daemonStart(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	if _, err := config.Require(ctx.Paths); err != nil {
+		return nil, err
+	}
+	state := daemon.State(ctx.Paths)
+	if state.Running {
+		return nil, errs.New(errs.CodeDaemonAlreadyRunning, "daemon 已在运行（pid "+strconv.Itoa(state.Lock.PID)+"）",
+			map[string]any{"pid": state.Lock.PID})
+	}
+	if state.Stale {
+		daemon.RemoveLock(ctx.Paths)
+	}
+	opts := startOptsFromCmd(cmd)
+	if flagBool(cmd, "no-detach") {
+		if err := daemon.RunForeground(ctx, opts); err != nil {
+			return nil, err
+		}
+		return map[string]any{"ok": true}, nil
+	}
+	lock, err := daemon.Spawn(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": true, "pid": lock.PID, "bind": lock.Bind, "port": lock.Port, "detached": true}, nil
+}
+
+func daemonStop(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return daemon.Stop(ctx.Paths)
+}
+
+func daemonRestart(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	lock := daemon.ReadLock(ctx.Paths)
+	opts := startOptsFromCmd(cmd)
+	if lock != nil {
+		if opts.Bind == "" {
+			opts.Bind = lock.Bind
+		}
+		if opts.Port == 0 {
+			opts.Port = lock.Port
+		}
+		if opts.LogLevel == "" {
+			opts.LogLevel = lock.LogLevel
+		}
+		if daemon.IsProcessAlive(lock.PID) {
+			if _, err := daemon.Stop(ctx.Paths); err != nil {
+				return nil, err
+			}
+		}
+	}
+	if _, err := config.Require(ctx.Paths); err != nil {
+		return nil, err
+	}
+	if flagBool(cmd, "no-detach") {
+		if err := daemon.RunForeground(ctx, opts); err != nil {
+			return nil, err
+		}
+		return map[string]any{"ok": true}, nil
+	}
+	newLock, err := daemon.Spawn(ctx, opts)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": true, "pid": newLock.PID, "bind": newLock.Bind, "port": newLock.Port, "detached": true}, nil
+}
+
+func daemonReload(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	state := daemon.State(ctx.Paths)
+	if !state.Running {
+		return map[string]any{"ok": true, "running": false, "reloaded": false}, nil
+	}
+	_, body, err := daemon.NewClient(ctx.Paths).Request("POST", "/daemon/reload", nil)
+	if err != nil {
+		return nil, err
+	}
+	return body, nil
+}
+
+func daemonStatus(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	state := daemon.State(ctx.Paths)
+	if !state.Running {
+		return nil, errs.New(errs.CodeDaemonNotRunning, "daemon 未运行",
+			map[string]any{"stale": state.Stale, "hint": "yoooclaw daemon start"})
+	}
+	_, body, err := daemon.NewClient(ctx.Paths).Request("GET", "/daemon/status", nil)
+	if err != nil {
+		return nil, err
+	}
+	return body, nil
+}
+
+func daemonLogs(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	n := atoiDefault(flagStr(cmd, "lines"), 100)
+	lines := tailLines(ctx.Paths.DaemonLog, n)
+	if level := flagStr(cmd, "level"); level != "" {
+		want := "[" + strings.ToUpper(level) + "]"
+		filtered := lines[:0]
+		for _, l := range lines {
+			if strings.Contains(l, want) {
+				filtered = append(filtered, l)
+			}
+		}
+		lines = filtered
+	}
+	// --follow 的实时 tail 暂不实现（Phase 2 标准输出即可）；返回当前快照。
+	return map[string]any{"ok": true, "file": ctx.Paths.DaemonLog, "total": len(lines), "lines": lines}, nil
+}
+
+func tailLines(file string, n int) []string {
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return []string{}
+	}
+	var lines []string
+	for _, l := range strings.Split(string(raw), "\n") {
+		if l != "" {
+			lines = append(lines, l)
+		}
+	}
+	if len(lines) > n {
+		lines = lines[len(lines)-n:]
+	}
+	return lines
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 152e5e3..97fd11f 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -30,6 +30,7 @@ func newRootCmd() *cobra.Command {
 		newConfigCmd(),
 		newProfileCmd(),
 		newAuthCmd(),
+		newDaemonCmd(),
 		newNotificationCmd(),
 		newLogCmd(),
 		newMigrateCmd(),
diff --git a/internal/daemon/client.go b/internal/daemon/client.go
new file mode 100644
index 0000000..97a750f
--- /dev/null
+++ b/internal/daemon/client.go
@@ -0,0 +1,98 @@
+package daemon
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// Client 是 CLI ↔ daemon 的内部 HTTP RPC（localhost）。
+type Client struct {
+	BaseURL string
+	token   string
+	timeout time.Duration
+}
+
+// NewClient 按 lock / config 推导 base URL 与 gateway token。
+func NewClient(p paths.Paths) *Client {
+	cfg, _ := config.Load(p)
+	state := State(p)
+	bind := cfg.Daemon.Bind
+	port := cfg.Daemon.Port
+	if state.Lock != nil {
+		bind = state.Lock.Bind
+		port = state.Lock.Port
+	}
+	host := bind
+	if host == "0.0.0.0" {
+		host = "127.0.0.1"
+	}
+	tokenRef, _ := creds.ResolveGatewayToken(cfg)
+	return &Client{
+		BaseURL: "http://" + host + ":" + strconv.Itoa(port),
+		token:   tokenRef.Value,
+		timeout: 10 * time.Second,
+	}
+}
+
+// Request 调 daemon；连接被拒/超时统一报 DAEMON_NOT_RUNNING。
+func (c *Client) Request(method, path string, body any) (int, any, error) {
+	var reader io.Reader
+	if body != nil {
+		data, _ := json.Marshal(body)
+		reader = bytes.NewReader(data)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), c.timeout)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, method, c.BaseURL+path, reader)
+	if err != nil {
+		return 0, nil, errs.New(errs.CodeNetworkError, "构造请求失败")
+	}
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		if strings.Contains(err.Error(), "connection refused") || ctx.Err() != nil {
+			return 0, nil, errs.New(errs.CodeDaemonNotRunning, "daemon 未启动或无响应",
+				map[string]any{"hint": "先执行 yoooclaw daemon start", "baseUrl": c.BaseURL})
+		}
+		return 0, nil, errs.New(errs.CodeNetworkError, "调用 daemon 失败："+err.Error())
+	}
+	defer resp.Body.Close()
+	text, _ := io.ReadAll(resp.Body)
+	var parsed any
+	if len(text) > 0 {
+		if json.Unmarshal(text, &parsed) != nil {
+			parsed = string(text)
+		}
+	}
+	if resp.StatusCode == 401 || resp.StatusCode == 403 {
+		return resp.StatusCode, parsed, errs.New(errs.CodeUnauthorized, "daemon 拒绝鉴权（token 不一致）",
+			map[string]any{"status": resp.StatusCode})
+	}
+	return resp.StatusCode, parsed, nil
+}
+
+// AssertRunning 确保 daemon 在运行，否则报 DAEMON_NOT_RUNNING（🟡 命令前置检查）。
+func AssertRunning(p paths.Paths) error {
+	state := State(p)
+	if !state.Running {
+		return errs.New(errs.CodeDaemonNotRunning, "daemon 未运行",
+			map[string]any{"hint": "先执行 yoooclaw daemon start", "stale": state.Stale})
+	}
+	return nil
+}
diff --git a/internal/daemon/lock.go b/internal/daemon/lock.go
index c7ca883..5d4863b 100644
--- a/internal/daemon/lock.go
+++ b/internal/daemon/lock.go
@@ -4,6 +4,8 @@
 package daemon
 
 import (
+	"os"
+
 	"github.com/YoooClaw/cli/internal/fsutil"
 	"github.com/YoooClaw/cli/internal/paths"
 )
@@ -44,3 +46,16 @@ func State(p paths.Paths) RunningState {
 	alive := isProcessAlive(lock.PID)
 	return RunningState{Running: alive, Lock: lock, Stale: !alive}
 }
+
+// WriteLock 写锁文件。
+func WriteLock(p paths.Paths, lock Lock) error {
+	return fsutil.WriteJSON(p.DaemonLock, lock, fsutil.ConfigFileMode)
+}
+
+// RemoveLock 删除锁文件。
+func RemoveLock(p paths.Paths) {
+	_ = os.Remove(p.DaemonLock)
+}
+
+// IsProcessAlive 导出探活（供 daemon 命令判断目标进程）。
+func IsProcessAlive(pid int) bool { return isProcessAlive(pid) }
diff --git a/internal/daemon/logger.go b/internal/daemon/logger.go
new file mode 100644
index 0000000..04968b1
--- /dev/null
+++ b/internal/daemon/logger.go
@@ -0,0 +1,97 @@
+package daemon
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+var levelOrder = map[string]int{"error": 0, "warn": 1, "info": 2, "debug": 3, "trace": 4}
+
+// Logger 是 daemon 文件 logger，写 daemon.log 并按日期轮转为 daemon.log.YYYY-MM-DD。
+// 行格式：`<ISO本地时间> [LEVEL] message`（与 logread 解析一致）。
+type Logger struct {
+	logFile    string
+	level      string
+	alsoStderr bool
+	mu         sync.Mutex
+	currentDay string
+}
+
+// NewLogger 构造 logger。
+func NewLogger(logFile, level string, alsoStderr bool) *Logger {
+	if level == "" {
+		level = "info"
+	}
+	_ = fsutil.EnsureDir(filepath.Dir(logFile), fsutil.DirMode)
+	l := &Logger{logFile: logFile, level: level, alsoStderr: alsoStderr, currentDay: dateKey(time.Now())}
+	l.rotateIfNeeded(time.Now())
+	return l
+}
+
+func dateKey(t time.Time) string { return t.Format("2006-01-02") }
+
+func isoLocal(t time.Time) string { return t.Format("2006-01-02T15:04:05.000Z07:00") }
+
+func (l *Logger) enabled(level string) bool {
+	lv, ok := levelOrder[level]
+	if !ok {
+		lv = 2
+	}
+	cur, ok := levelOrder[l.level]
+	if !ok {
+		cur = 2
+	}
+	return lv <= cur
+}
+
+func (l *Logger) rotateIfNeeded(now time.Time) {
+	info, err := os.Stat(l.logFile)
+	if err != nil {
+		return
+	}
+	fileDay := dateKey(info.ModTime())
+	if fileDay != dateKey(now) {
+		_ = os.Rename(l.logFile, l.logFile+"."+fileDay)
+	}
+}
+
+func (l *Logger) write(level, msg string) {
+	if !l.enabled(level) {
+		return
+	}
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	now := time.Now()
+	if dateKey(now) != l.currentDay {
+		l.rotateIfNeeded(now)
+		l.currentDay = dateKey(now)
+	}
+	line := isoLocal(now) + " [" + upper(level) + "] " + msg + "\n"
+	if f, err := os.OpenFile(l.logFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644); err == nil {
+		_, _ = f.WriteString(line)
+		_ = f.Close()
+	}
+	if l.alsoStderr {
+		_, _ = os.Stderr.WriteString(line)
+	}
+}
+
+func upper(s string) string {
+	b := []byte(s)
+	for i := range b {
+		if b[i] >= 'a' && b[i] <= 'z' {
+			b[i] -= 32
+		}
+	}
+	return string(b)
+}
+
+// Debug/Info/Warn/Error 写对应级别日志。
+func (l *Logger) Debug(msg string) { l.write("debug", msg) }
+func (l *Logger) Info(msg string)  { l.write("info", msg) }
+func (l *Logger) Warn(msg string)  { l.write("warn", msg) }
+func (l *Logger) Error(msg string) { l.write("error", msg) }
diff --git a/internal/daemon/proc_unix.go b/internal/daemon/proc_unix.go
index 47ffdeb..a3ec2d6 100644
--- a/internal/daemon/proc_unix.go
+++ b/internal/daemon/proc_unix.go
@@ -18,3 +18,14 @@ func isProcessAlive(pid int) bool {
 	}
 	return errors.Is(err, syscall.EPERM)
 }
+
+// detachSysProcAttr 让 fork 出的 daemon 子进程脱离当前会话（独立进程组）。
+func detachSysProcAttr() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{Setsid: true}
+}
+
+// terminate 向进程发送 SIGTERM（优雅）。
+func terminate(pid int) error { return syscall.Kill(pid, syscall.SIGTERM) }
+
+// forceKill 向进程发送 SIGKILL（强杀）。
+func forceKill(pid int) error { return syscall.Kill(pid, syscall.SIGKILL) }
diff --git a/internal/daemon/proc_windows.go b/internal/daemon/proc_windows.go
index 6de8205..fae7e81 100644
--- a/internal/daemon/proc_windows.go
+++ b/internal/daemon/proc_windows.go
@@ -2,7 +2,10 @@
 
 package daemon
 
-import "os"
+import (
+	"os"
+	"syscall"
+)
 
 // isProcessAlive 在 Windows 上 best-effort：FindProcess 成功即视为存活。
 // （daemon 主要运行于 unix；Windows 探活精度有限，Phase 2 视需要再加固。）
@@ -13,3 +16,19 @@ func isProcessAlive(pid int) bool {
 	_, err := os.FindProcess(pid)
 	return err == nil
 }
+
+// detachSysProcAttr 在 Windows 上新建进程组以脱离父进程。
+func detachSysProcAttr() *syscall.SysProcAttr {
+	return &syscall.SysProcAttr{CreationFlags: 0x00000200} // CREATE_NEW_PROCESS_GROUP
+}
+
+// terminate / forceKill：Windows 无 POSIX 信号，统一调用 Kill（TerminateProcess）。
+func terminate(pid int) error {
+	p, err := os.FindProcess(pid)
+	if err != nil {
+		return err
+	}
+	return p.Kill()
+}
+
+func forceKill(pid int) error { return terminate(pid) }
diff --git a/internal/daemon/server.go b/internal/daemon/server.go
new file mode 100644
index 0000000..b666d65
--- /dev/null
+++ b/internal/daemon/server.go
@@ -0,0 +1,349 @@
+package daemon
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/config"
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/notif"
+	"github.com/YoooClaw/cli/internal/version"
+)
+
+// ProtocolVersion 是手机端协议协商版本。
+const ProtocolVersion = 1
+
+// Capabilities 是本 build 支持的能力（Phase 2 标准 HTTP，relay/recordings/images 待后续）。
+var Capabilities = []string{"notifications", "multi-apikey"}
+
+// StartOpts 是 daemon 启动参数。
+type StartOpts struct {
+	Bind     string
+	Port     int
+	LogLevel string
+}
+
+type runtimeState struct {
+	startedAt   string
+	mu          sync.Mutex
+	lastIngest  string
+	ingestCount int
+}
+
+// RunForeground 前台运行 daemon 主循环（detach 子进程入口）。永不正常返回。
+func RunForeground(ctx *clictx.Context, opts StartOpts) error {
+	if State(ctx.Paths).Running {
+		return errs.New(errs.CodeDaemonAlreadyRunning, "daemon 已在运行")
+	}
+	cfg, err := config.Load(ctx.Paths)
+	if err != nil {
+		return err
+	}
+	bind := firstNonEmptyStr(opts.Bind, cfg.Daemon.Bind)
+	port := opts.Port
+	if port == 0 {
+		port = cfg.Daemon.Port
+	}
+	logLevel := firstNonEmptyStr(opts.LogLevel, cfg.Daemon.LogLevel)
+	tokenRef, _ := creds.ResolveGatewayToken(cfg)
+	token := tokenRef.Value
+	credentialSet := creds.ResolveAPIKeyEntries()
+
+	loopback := bind == "127.0.0.1" || bind == "::1" || bind == "localhost"
+	if !loopback && token == "" {
+		return errs.New(errs.CodeUnauthorized, "绑定 "+bind+" 需要先设置 gateway token").
+			WithHint("运行 yoooclaw auth token-rotate 或改回 127.0.0.1")
+	}
+
+	_ = fsutil.EnsureDir(ctx.Paths.Dir, fsutil.DirMode)
+	logger := NewLogger(ctx.Paths.DaemonLog, logLevel, false)
+	st := &runtimeState{startedAt: time.Now().UTC().Format(time.RFC3339)}
+
+	storage := notif.NewStorage(ctx.Paths.Notifications, notif.PluginConfig{
+		RetentionDays: cfg.Notification.RetentionDays, IgnoredApps: cfg.Notification.IgnoredApps,
+	}, logger)
+	if err := storage.Init(); err != nil {
+		return err
+	}
+	ignored := map[string]bool{}
+	for _, a := range cfg.Notification.IgnoredApps {
+		ignored[a] = true
+	}
+
+	srv := &server{
+		ctx: ctx, cfg: cfg, logger: logger, st: st, storage: storage,
+		token: token, credentialSet: credentialSet, ignored: ignored, bind: bind,
+	}
+
+	// 监听；端口被占自动 +1（最多 64 次）。
+	ln, actualPort, err := listenWithFallback(bind, port, logger)
+	if err != nil {
+		return err
+	}
+	srv.port = actualPort
+
+	httpSrv := &http.Server{Handler: srv}
+	if err := WriteLock(ctx.Paths, Lock{PID: os.Getpid(), StartedAt: st.startedAt, Bind: bind, Port: actualPort, LogLevel: logLevel}); err != nil {
+		return err
+	}
+	logger.Info(fmt.Sprintf("yoooclaw daemon 启动：%s:%d（profile=%s, pid=%d）", bind, actualPort, ctx.Profile, os.Getpid()))
+	if cfg.Relay.Enabled {
+		logger.Warn("Relay 已启用，但本 build 暂未实现隧道（Phase 3）；当前仅直连 HTTP")
+	}
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, syscall.SIGTERM, syscall.SIGINT)
+	srv.shutdown = func(reason string) {
+		logger.Info("daemon 退出（" + reason + "）")
+		_ = httpSrv.Close()
+		RemoveLock(ctx.Paths)
+		os.Exit(0)
+	}
+
+	go func() {
+		<-stop
+		srv.shutdown("signal")
+	}()
+
+	if err := httpSrv.Serve(ln); err != nil && err != http.ErrServerClosed {
+		logger.Error("HTTP server 异常：" + err.Error())
+		RemoveLock(ctx.Paths)
+		return err
+	}
+	return nil
+}
+
+type server struct {
+	ctx           *clictx.Context
+	cfg           config.Config
+	logger        *Logger
+	st            *runtimeState
+	storage       *notif.Storage
+	token         string
+	credentialSet creds.CredentialSet
+	ignored       map[string]bool
+	bind          string
+	port          int
+	shutdown      func(string)
+}
+
+func (s *server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	defer func() {
+		if rec := recover(); rec != nil {
+			s.logger.Error(fmt.Sprintf("请求处理异常：%v", rec))
+			writeJSON(w, 500, map[string]any{"ok": false, "error": map[string]any{"code": "INTERNAL_ERROR", "message": fmt.Sprintf("%v", rec)}})
+		}
+	}()
+	path := r.URL.Path
+
+	if path == "/health" && r.Method == http.MethodGet {
+		writeJSON(w, 200, map[string]any{"server": "yoooclaw", "version": version.Version, "protocol": ProtocolVersion, "capabilities": Capabilities})
+		return
+	}
+
+	authCtx, ok := s.authContext(r, path)
+	if !ok {
+		writeJSON(w, 401, map[string]any{"ok": false, "error": map[string]any{"code": errs.CodeUnauthorized, "message": "token 不一致或缺失"}})
+		return
+	}
+
+	switch {
+	case path == "/daemon/status" && r.Method == http.MethodGet:
+		s.handleStatus(w)
+	case path == "/daemon/stop" && r.Method == http.MethodPost:
+		writeJSON(w, 200, map[string]any{"ok": true, "stopping": true})
+		s.logger.Info("收到 /daemon/stop，准备优雅退出")
+		go func() { time.Sleep(50 * time.Millisecond); s.shutdown("stop-endpoint") }()
+	case path == "/daemon/reload" && r.Method == http.MethodPost:
+		s.credentialSet = creds.ResolveAPIKeyEntries()
+		writeJSON(w, 200, map[string]any{"ok": true, "running": true, "reloaded": true, "mode": s.credentialSet.Mode})
+	case path == "/notifications" && r.Method == http.MethodPost:
+		s.handleIngest(w, r, authCtx, "notifications")
+	case path == "/gateway/notifications.push" && r.Method == http.MethodPost:
+		s.handleIngest(w, r, authCtx, "items")
+	default:
+		writeJSON(w, 404, map[string]any{"ok": false, "error": map[string]any{"code": errs.CodeNotFound, "message": "未知路径：" + path}})
+	}
+}
+
+type authResult struct {
+	clientLabel string
+	authKind    string
+}
+
+func (s *server) authContext(r *http.Request, path string) (authResult, bool) {
+	bearer := bearerValue(r)
+	if s.token != "" && bearer == s.token {
+		return authResult{clientLabel: "local", authKind: "gateway-token"}, true
+	}
+	if isIngestPath(path) {
+		if label := s.labelForAPIKey(bearer); label != "" {
+			return authResult{clientLabel: label, authKind: "http-api-key"}, true
+		}
+	}
+	if s.token == "" {
+		return authResult{clientLabel: "local", authKind: "local"}, true
+	}
+	return authResult{}, false
+}
+
+func (s *server) labelForAPIKey(apiKey string) string {
+	if apiKey == "" {
+		return ""
+	}
+	raw := strings.TrimPrefix(apiKey, "Bearer ")
+	for _, e := range s.credentialSet.Entries {
+		if strings.TrimPrefix(e.Key, "Bearer ") == raw {
+			return e.Label
+		}
+	}
+	return ""
+}
+
+func (s *server) handleIngest(w http.ResponseWriter, r *http.Request, auth authResult, field string) {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		writeJSON(w, 400, errBody("INVALID_PARAMS", "读取请求体失败"))
+		return
+	}
+	var raw map[string]json.RawMessage
+	if len(body) > 0 {
+		if json.Unmarshal(body, &raw) != nil {
+			writeJSON(w, 400, errBody("INVALID_PARAMS", "请求体不是合法 JSON"))
+			return
+		}
+	}
+	var items []notif.RawNotification
+	// 兼容 {notifications:[]} / {items:[]} / {params:{items:[]}}。
+	for _, key := range []string{field, "notifications", "items"} {
+		if rawItems, ok := raw[key]; ok {
+			_ = json.Unmarshal(rawItems, &items)
+			break
+		}
+	}
+	if items == nil {
+		if p, ok := raw["params"]; ok {
+			var params struct {
+				Items []notif.RawNotification `json:"items"`
+			}
+			_ = json.Unmarshal(p, &params)
+			items = params.Items
+		}
+	}
+	// 过滤 ignoredApps。
+	filtered := items[:0]
+	for _, it := range items {
+		if !s.ignored[it.App] {
+			filtered = append(filtered, it)
+		}
+	}
+	result := s.storage.Ingest(filtered, auth.clientLabel)
+	s.st.mu.Lock()
+	s.st.lastIngest = time.Now().UTC().Format(time.RFC3339)
+	s.st.ingestCount += result.Ingested
+	s.st.mu.Unlock()
+	writeJSON(w, 200, map[string]any{
+		"ok": true, "received": result.Received, "ingested": result.Ingested,
+		"dedupedById": result.DedupedByID, "dedupedByContent": result.DedupedByContent, "invalid": result.Invalid,
+	})
+}
+
+func (s *server) handleStatus(w http.ResponseWriter) {
+	s.st.mu.Lock()
+	lastIngest := s.st.lastIngest
+	ingestCount := s.st.ingestCount
+	s.st.mu.Unlock()
+	var defaultLabel any
+	if s.credentialSet.DefaultEntry != nil {
+		defaultLabel = s.credentialSet.DefaultEntry.Label
+	}
+	writeJSON(w, 200, map[string]any{
+		"ok": true, "server": "yoooclaw", "version": version.Version, "pid": os.Getpid(),
+		"profile": s.ctx.Profile, "bind": s.bind, "port": s.port, "startedAt": s.st.startedAt,
+		"lastIngestAt": nilIfEmptyStr(lastIngest), "ingestCount": ingestCount,
+		"relay": map[string]any{
+			"mode": "standalone-http", "connected": false, "url": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
+			"note": "本 build 未实现 Relay 隧道（Phase 3），仅直连 HTTP",
+		},
+		"credentialMode": s.credentialSet.Mode, "defaultLabel": defaultLabel,
+		"credentialWarnings": s.credentialSet.Warnings,
+	})
+}
+
+// ── helpers ──
+
+func isIngestPath(path string) bool {
+	switch path {
+	case "/notifications", "/recordings", "/images",
+		"/gateway/notifications.push", "/gateway/recordings.sync", "/gateway/images.sync":
+		return true
+	}
+	return false
+}
+
+func bearerValue(r *http.Request) string {
+	h := strings.TrimSpace(r.Header.Get("Authorization"))
+	if !strings.HasPrefix(strings.ToLower(h), "bearer ") {
+		return ""
+	}
+	return strings.TrimSpace(h[len("Bearer "):])
+}
+
+func listenWithFallback(bind string, startPort int, logger *Logger) (net.Listener, int, error) {
+	port := startPort
+	for attempt := 0; attempt < 64; attempt++ {
+		ln, err := net.Listen("tcp", fmt.Sprintf("%s:%d", bind, port))
+		if err == nil {
+			if port != startPort {
+				logger.Info(fmt.Sprintf("起始端口 %d 被占用，最终绑定到 %d", startPort, port))
+			}
+			return ln, port, nil
+		}
+		if !strings.Contains(err.Error(), "address already in use") {
+			return nil, 0, err
+		}
+		logger.Warn(fmt.Sprintf("端口 %d 被占用，改试 %d", port, port+1))
+		port++
+	}
+	return nil, 0, errs.New(errs.CodeUnknown, "无可用端口")
+}
+
+func writeJSON(w http.ResponseWriter, status int, body any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	enc := json.NewEncoder(w)
+	enc.SetEscapeHTML(false)
+	_ = enc.Encode(body)
+}
+
+func errBody(code, msg string) map[string]any {
+	return map[string]any{"ok": false, "error": map[string]any{"code": code, "message": msg}}
+}
+
+func firstNonEmptyStr(values ...string) string {
+	for _, v := range values {
+		if v != "" {
+			return v
+		}
+	}
+	return ""
+}
+
+func nilIfEmptyStr(s string) any {
+	if s == "" {
+		return nil
+	}
+	return s
+}
diff --git a/internal/daemon/spawn.go b/internal/daemon/spawn.go
new file mode 100644
index 0000000..1b9a30a
--- /dev/null
+++ b/internal/daemon/spawn.go
@@ -0,0 +1,77 @@
+package daemon
+
+import (
+	"os"
+	"os/exec"
+	"runtime"
+	"strconv"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// Spawn fork 一个脱离会话的子进程跑 `daemon run-foreground`，轮询 lock 确认起来（最多 ~3s）。
+func Spawn(ctx *clictx.Context, opts StartOpts) (*Lock, error) {
+	exe, err := os.Executable()
+	if err != nil {
+		return nil, errs.New(errs.CodeUnknown, "无法定位可执行文件："+err.Error())
+	}
+	args := []string{"daemon", "run-foreground", "--profile", ctx.Profile}
+	if opts.Bind != "" {
+		args = append(args, "--bind", opts.Bind)
+	}
+	if opts.Port != 0 {
+		args = append(args, "--port", strconv.Itoa(opts.Port))
+	}
+	if opts.LogLevel != "" {
+		args = append(args, "--log-level", opts.LogLevel)
+	}
+	cmd := exec.Command(exe, args...)
+	cmd.SysProcAttr = detachSysProcAttr()
+	if null, err := os.OpenFile(os.DevNull, os.O_RDWR, 0); err == nil {
+		cmd.Stdin, cmd.Stdout, cmd.Stderr = null, null, null
+	}
+	cmd.Env = os.Environ()
+	if err := cmd.Start(); err != nil {
+		return nil, errs.New(errs.CodeUnknown, "fork daemon 失败："+err.Error())
+	}
+	_ = cmd.Process.Release()
+
+	for i := 0; i < 30; i++ {
+		time.Sleep(100 * time.Millisecond)
+		if st := State(ctx.Paths); st.Running {
+			return st.Lock, nil
+		}
+	}
+	return nil, errs.New(errs.CodeUnknown, "daemon 启动超时（3s 内未写出 lock）").
+		WithHint("查看 yoooclaw daemon logs 排查")
+}
+
+// Stop 停止 daemon：unix 发 SIGTERM 走优雅退出，Windows 打 /daemon/stop 端点；
+// 10s 内未退则强杀。
+func Stop(p paths.Paths) (map[string]any, error) {
+	lock := ReadLock(p)
+	if lock == nil || !isProcessAlive(lock.PID) {
+		RemoveLock(p)
+		return nil, errs.New(errs.CodeDaemonNotRunning, "daemon 未运行")
+	}
+	signal := "SIGTERM"
+	if runtime.GOOS == "windows" {
+		signal = "stop-endpoint"
+		_, _, _ = NewClient(p).Request("POST", "/daemon/stop", nil)
+	} else {
+		_ = terminate(lock.PID)
+	}
+	for i := 0; i < 100; i++ {
+		time.Sleep(100 * time.Millisecond)
+		if !isProcessAlive(lock.PID) {
+			RemoveLock(p)
+			return map[string]any{"ok": true, "stopped": lock.PID, "signal": signal}, nil
+		}
+	}
+	_ = forceKill(lock.PID)
+	RemoveLock(p)
+	return map[string]any{"ok": true, "stopped": lock.PID, "signal": "SIGKILL"}, nil
+}
diff --git a/internal/notif/feishu.go b/internal/notif/feishu.go
new file mode 100644
index 0000000..245a238
--- /dev/null
+++ b/internal/notif/feishu.go
@@ -0,0 +1,154 @@
+package notif
+
+import "strings"
+
+// feishuFields 是从飞书通知派生的结构化字段。
+type feishuFields struct {
+	SenderName       string
+	ConversationType string
+	ConversationName string
+}
+
+type feishuNormalized struct {
+	Title      string
+	Content    string
+	Structured feishuFields
+}
+
+func normOptText(v any) string {
+	s, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return strings.TrimSpace(s)
+}
+
+func isFeishuApp(appName string) bool {
+	n := strings.ToLower(strings.TrimSpace(appName))
+	if n == "" {
+		return false
+	}
+	switch n {
+	case "飞书", "feishu", "lark", "com.ss.android.lark", "com.bytedance.ee.lark", "com.larksuite.suite":
+		return true
+	}
+	return strings.Contains(n, "feishu") || strings.Contains(n, "lark") || strings.Contains(n, "飞书")
+}
+
+func isFeishuAppLabel(text string) bool {
+	t := strings.ToLower(strings.TrimSpace(text))
+	return t == "飞书" || t == "lark" || t == "feishu"
+}
+
+func extractColonSender(body string) string {
+	if body == "" {
+		return ""
+	}
+	idx := -1
+	for _, sep := range []string{":", "："} {
+		if i := strings.Index(body, sep); i > 0 {
+			if idx == -1 || i < idx {
+				idx = i
+			}
+		}
+	}
+	if idx <= 0 {
+		return ""
+	}
+	return strings.TrimSpace(body[:idx])
+}
+
+// findMetadataTextByKey 在嵌套 metadata 中递归查找 key（大小写不敏感），返回首个命中的归一文本。
+func findMetadataTextByKey(value any, targetKey string, depth int) (found bool, text string) {
+	if value == nil || depth > 4 {
+		return false, ""
+	}
+	switch v := value.(type) {
+	case []any:
+		for _, item := range v {
+			if f, t := findMetadataTextByKey(item, targetKey, depth+1); f {
+				return true, t
+			}
+		}
+		return false, ""
+	case map[string]any:
+		for key, child := range v {
+			if strings.ToLower(strings.TrimSpace(key)) == targetKey {
+				return true, normOptText(child)
+			}
+		}
+		for _, child := range v {
+			if f, t := findMetadataTextByKey(child, targetKey, depth+1); f {
+				return true, t
+			}
+		}
+		return false, ""
+	default:
+		return false, ""
+	}
+}
+
+func deriveStructured(n RawNotification) feishuFields {
+	found, subtitle := findMetadataTextByKey(n.Metadata, "subtitle", 0)
+	if found {
+		out := feishuFields{}
+		if subtitle != "" {
+			out.ConversationType = "group"
+			out.ConversationName = subtitle
+		} else {
+			out.ConversationType = "private"
+		}
+		if sender := normOptText(n.Title); sender != "" {
+			out.SenderName = sender
+		}
+		return out
+	}
+	if isFeishuAppLabel(n.Title) {
+		if sender := extractColonSender(n.Body); sender != "" {
+			return feishuFields{SenderName: sender, ConversationType: "private"}
+		}
+	}
+	return feishuFields{}
+}
+
+func buildFeishuTitle(n RawNotification, s feishuFields) string {
+	if s.ConversationType == "group" && s.ConversationName != "" {
+		return s.ConversationName
+	}
+	if s.ConversationType == "private" && s.SenderName != "" {
+		return s.SenderName
+	}
+	return n.Title
+}
+
+func buildFeishuContent(n RawNotification, s feishuFields) string {
+	body := strings.TrimSpace(n.Body)
+	if s.ConversationType == "group" && s.SenderName != "" && body != "" {
+		if strings.HasPrefix(body, s.SenderName+":") || strings.HasPrefix(body, s.SenderName+"：") {
+			return body
+		}
+		return s.SenderName + ": " + body
+	}
+	if s.ConversationType == "private" && s.SenderName != "" && body != "" {
+		if strings.HasPrefix(body, s.SenderName+":") {
+			return strings.TrimLeft(body[len(s.SenderName+":"):], " ")
+		}
+		if strings.HasPrefix(body, s.SenderName+"：") {
+			return strings.TrimLeft(body[len(s.SenderName+"："):], " ")
+		}
+		return body
+	}
+	return body
+}
+
+// normalizeFeishuFields 归一化飞书通知；非飞书或无任何结构化命中返回 (nil,false)。
+func normalizeFeishuFields(n RawNotification) (feishuNormalized, bool) {
+	if !isFeishuApp(n.App) {
+		return feishuNormalized{}, false
+	}
+	s := deriveStructured(n)
+	if s.SenderName == "" && s.ConversationType == "" && s.ConversationName == "" {
+		return feishuNormalized{}, false
+	}
+	return feishuNormalized{Title: buildFeishuTitle(n, s), Content: buildFeishuContent(n, s), Structured: s}, true
+}
diff --git a/internal/notif/storage.go b/internal/notif/storage.go
new file mode 100644
index 0000000..2e32c47
--- /dev/null
+++ b/internal/notif/storage.go
@@ -0,0 +1,352 @@
+package notif
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+)
+
+var dateDirRE = regexp.MustCompile(`^\d{4}-\d{2}-\d{2}$`)
+
+const (
+	idIndexDirName         = ".ids"
+	contentKeyIndexDirName = ".keys"
+	unitSep                = "\x1f"
+)
+
+// Logger 是存储层依赖的最小日志接口。
+type Logger interface {
+	Info(string)
+	Warn(string)
+}
+
+// IngestResult 是一次 ingest 的统计 + 新插入条目。
+type IngestResult struct {
+	Received         int                  `json:"received"`
+	Ingested         int                  `json:"ingested"`
+	DedupedByID      int                  `json:"dedupedById"`
+	DedupedByContent int                  `json:"dedupedByContent"`
+	Invalid          int                  `json:"invalid"`
+	Inserted         []StoredNotification `json:"-"`
+}
+
+// Storage 是 date-keyed JSON 通知存储（含 id / content-key 双重去重）。
+type Storage struct {
+	dir            string
+	idIndexDir     string
+	contentKeyDir  string
+	cfg            PluginConfig
+	logger         Logger
+	mu             sync.Mutex
+	idCache        map[string]map[string]bool
+	contentKeyCach map[string]map[string]bool
+}
+
+// NewStorage 构造存储；dir 为 notifications 目录。
+func NewStorage(dir string, cfg PluginConfig, logger Logger) *Storage {
+	return &Storage{
+		dir:            dir,
+		idIndexDir:     filepath.Join(dir, idIndexDirName),
+		contentKeyDir:  filepath.Join(dir, contentKeyIndexDirName),
+		cfg:            cfg,
+		logger:         logger,
+		idCache:        map[string]map[string]bool{},
+		contentKeyCach: map[string]map[string]bool{},
+	}
+}
+
+// Init 准备目录；content-key 索引每次启动重建。
+func (s *Storage) Init() error {
+	if err := os.MkdirAll(s.dir, 0o755); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(s.idIndexDir, 0o755); err != nil {
+		return err
+	}
+	_ = os.RemoveAll(s.contentKeyDir)
+	return os.MkdirAll(s.contentKeyDir, 0o755)
+}
+
+// Ingest 写入一批通知，去重后返回统计与新插入条目。clientLabel 为来源（缺省 "default"）。
+func (s *Storage) Ingest(items []RawNotification, clientLabel string) IngestResult {
+	if clientLabel == "" {
+		clientLabel = "default"
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	result := IngestResult{Received: len(items)}
+	for _, n := range items {
+		kind, entry := s.writeOne(n, clientLabel)
+		switch kind {
+		case "ingested":
+			result.Ingested++
+			result.Inserted = append(result.Inserted, entry)
+		case "dedupedById":
+			result.DedupedByID++
+		case "dedupedByContent":
+			result.DedupedByContent++
+		case "invalid":
+			result.Invalid++
+		}
+	}
+	s.prune()
+	return result
+}
+
+func (s *Storage) writeOne(n RawNotification, clientLabel string) (string, StoredNotification) {
+	ts, ok := ParseTime(n.Timestamp)
+	if !ok {
+		s.logger.Warn("忽略非法 timestamp 的通知: " + n.ID)
+		return "invalid", StoredNotification{}
+	}
+	dateKey := ts.In(time.Local).Format("2006-01-02")
+	filePath := filepath.Join(s.dir, dateKey+".json")
+	normalizedID := strings.TrimSpace(n.ID)
+	entry := s.buildStored(n, clientLabel)
+
+	if normalizedID != "" && s.hasID(dateKey, labelOrLegacy(entry.ClientLabel), normalizedID) {
+		return "dedupedById", StoredNotification{}
+	}
+	if s.hasContentKey(dateKey, filePath, entry) {
+		return "dedupedByContent", StoredNotification{}
+	}
+
+	if entry.AppDisplayName == "" {
+		entry.AppDisplayName = entry.AppName
+	}
+	arr := readStoredFile(filePath)
+	arr = append(arr, entry)
+	if data, err := json.MarshalIndent(arr, "", "  "); err == nil {
+		_ = os.WriteFile(filePath, data, 0o644)
+	}
+
+	if normalizedID != "" {
+		s.recordID(dateKey, labelOrLegacy(entry.ClientLabel), normalizedID)
+	}
+	s.recordContentKey(dateKey, filePath, entry)
+	return "ingested", entry
+}
+
+func (s *Storage) buildStored(n RawNotification, clientLabel string) StoredNotification {
+	appName := n.App
+	if appName == "" {
+		appName = "Unknown"
+	}
+	if feishu, ok := normalizeFeishuFields(n); ok {
+		content := feishu.Content
+		if content == "" {
+			content = buildFallbackContent(n)
+		}
+		return StoredNotification{
+			ClientLabel: clientLabel, AppName: appName, Title: feishu.Title, Content: content,
+			Timestamp: n.Timestamp, SenderName: feishu.Structured.SenderName,
+			ConversationType: feishu.Structured.ConversationType, ConversationName: feishu.Structured.ConversationName,
+		}
+	}
+	return StoredNotification{
+		ClientLabel: clientLabel, AppName: appName, Title: n.Title,
+		Content: buildFallbackContent(n), Timestamp: n.Timestamp,
+	}
+}
+
+func buildFallbackContent(n RawNotification) string {
+	if body := strings.TrimSpace(n.Body); body != "" {
+		return body
+	}
+	var parts []string
+	if n.Category != "" {
+		parts = append(parts, "category:"+n.Category)
+	}
+	if len(n.Metadata) > 0 {
+		if b, err := json.Marshal(n.Metadata); err == nil {
+			parts = append(parts, "metadata:"+string(b))
+		}
+	}
+	if len(parts) == 0 {
+		return "-"
+	}
+	return strings.Join(parts, " ; ")
+}
+
+func labelOrLegacy(label string) string {
+	if label == "" {
+		return "legacy"
+	}
+	return label
+}
+
+func usesLegacyIDKey(label string) bool {
+	return label == "legacy" || label == "default"
+}
+
+func (s *Storage) idKey(label, id string) string {
+	if usesLegacyIDKey(label) {
+		return id
+	}
+	return label + unitSep + id
+}
+
+func (s *Storage) idSet(dateKey string) map[string]bool {
+	if set, ok := s.idCache[dateKey]; ok {
+		return set
+	}
+	set := map[string]bool{}
+	if raw, err := os.ReadFile(filepath.Join(s.idIndexDir, dateKey+".ids")); err == nil {
+		for _, line := range strings.Split(string(raw), "\n") {
+			if id := strings.TrimSpace(line); id != "" {
+				set[id] = true
+			}
+		}
+	}
+	s.idCache[dateKey] = set
+	return set
+}
+
+func (s *Storage) hasID(dateKey, label, id string) bool {
+	set := s.idSet(dateKey)
+	if set[s.idKey(label, id)] {
+		return true
+	}
+	return usesLegacyIDKey(label) && set[id]
+}
+
+func (s *Storage) recordID(dateKey, label, id string) {
+	set := s.idSet(dateKey)
+	key := s.idKey(label, id)
+	if set[key] {
+		return
+	}
+	appendLine(filepath.Join(s.idIndexDir, dateKey+".ids"), key)
+	set[key] = true
+}
+
+func contentKey(e StoredNotification) string {
+	h := sha256.New()
+	h.Write([]byte(labelOrLegacy(e.ClientLabel)))
+	h.Write([]byte(unitSep))
+	h.Write([]byte(e.AppName))
+	h.Write([]byte(unitSep))
+	h.Write([]byte(e.Title))
+	h.Write([]byte(unitSep))
+	h.Write([]byte(e.Content))
+	h.Write([]byte(unitSep))
+	h.Write([]byte(e.Timestamp))
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+func (s *Storage) contentKeySet(dateKey, filePath string) map[string]bool {
+	if set, ok := s.contentKeyCach[dateKey]; ok {
+		return set
+	}
+	set := map[string]bool{}
+	keyPath := filepath.Join(s.contentKeyDir, dateKey+".keys")
+	for _, item := range readStoredFile(filePath) {
+		set[contentKey(item)] = true
+	}
+	if len(set) > 0 {
+		var b strings.Builder
+		for k := range set {
+			b.WriteString(k)
+			b.WriteString("\n")
+		}
+		_ = os.WriteFile(keyPath, []byte(b.String()), 0o644)
+	} else {
+		_ = os.Remove(keyPath)
+	}
+	s.contentKeyCach[dateKey] = set
+	return set
+}
+
+func (s *Storage) hasContentKey(dateKey, filePath string, e StoredNotification) bool {
+	set := s.contentKeySet(dateKey, filePath)
+	for _, label := range contentKeyLabels(e.ClientLabel) {
+		probe := e
+		probe.ClientLabel = label
+		if set[contentKey(probe)] {
+			return true
+		}
+	}
+	return false
+}
+
+func contentKeyLabels(label string) []string {
+	l := labelOrLegacy(label)
+	if l == "default" {
+		return []string{"default", "legacy"}
+	}
+	return []string{l}
+}
+
+func (s *Storage) recordContentKey(dateKey, filePath string, e StoredNotification) {
+	set := s.contentKeySet(dateKey, filePath)
+	key := contentKey(e)
+	if set[key] {
+		return
+	}
+	appendLine(filepath.Join(s.contentKeyDir, dateKey+".keys"), key)
+	set[key] = true
+}
+
+func (s *Storage) prune() {
+	if s.cfg.RetentionDays == nil {
+		return
+	}
+	cutoff := time.Now().Add(-time.Duration(*s.cfg.RetentionDays) * 24 * time.Hour).In(time.Local).Format("2006-01-02")
+	pruneByDate(s.dir, cutoff, []string{".json", ".md"}, func(k string) { delete(s.idCache, k); delete(s.contentKeyCach, k) }, false)
+	pruneByDate(s.idIndexDir, cutoff, []string{".ids"}, func(k string) { delete(s.idCache, k) }, true)
+	pruneByDate(s.contentKeyDir, cutoff, []string{".keys"}, func(k string) { delete(s.contentKeyCach, k) }, true)
+}
+
+func pruneByDate(dir, cutoff string, exts []string, evict func(string), filesOnly bool) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		name := e.Name()
+		if e.IsDir() {
+			if !filesOnly && len(name) == 10 && name < cutoff && dateDirRE.MatchString(name) {
+				_ = os.RemoveAll(filepath.Join(dir, name))
+			}
+			continue
+		}
+		for _, ext := range exts {
+			if strings.HasSuffix(name, ext) {
+				key := strings.TrimSuffix(name, ext)
+				if len(key) == 10 && key < cutoff {
+					_ = os.Remove(filepath.Join(dir, name))
+					evict(key)
+				}
+				break
+			}
+		}
+	}
+}
+
+func readStoredFile(filePath string) []StoredNotification {
+	raw, err := os.ReadFile(filePath)
+	if err != nil {
+		return nil
+	}
+	var items []StoredNotification
+	if json.Unmarshal(raw, &items) != nil {
+		return nil
+	}
+	return items
+}
+
+func appendLine(path, line string) {
+	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		return
+	}
+	defer f.Close()
+	_, _ = f.WriteString(line + "\n")
+}

From 1f9fd7a1ff35374570e9bb1cfcc34801c7e14483 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 17:14:54 +0800
Subject: [PATCH 04/13] =?UTF-8?q?feat(go):=20Phase=202=20=E6=95=B0?=
 =?UTF-8?q?=E6=8D=AE=E9=9D=A2=E8=AF=BB=E4=BE=A7=20=E2=80=94=20recording=20?=
 =?UTF-8?q?+=20image=20=E6=9F=A5=E8=AF=A2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- internal/recording：读 recordings/index.json + state/events.jsonl
- internal/image：读 images/index.json + 相对路径解析
- cli recording：list/status/storage-path/setup-asr/events/+latest
  （setup-asr 写 AsrConfig 兼容结构；events 按 id/since/limit 过滤）
- cli image：list/status/path/storage-path/+latest
  （list 支持 status/client/app 别名/from-to/limit；path 校验 synced + IMAGE_NOT_READY）

验证：合成 index.json/events.jsonl 跑通 recording list/+latest/events/setup-asr、
image list（wechat 别名匹配 source_app）/path 解析。ingest 写侧（含 OSS 下载）待后续。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/cli/cmd_image.go     | 123 ++++++++++++++++
 internal/cli/cmd_recording.go | 256 ++++++++++++++++++++++++++++++++++
 internal/cli/root.go          |   2 +
 internal/image/store.go       |  65 +++++++++
 internal/recording/store.go   |  84 +++++++++++
 5 files changed, 530 insertions(+)
 create mode 100644 internal/cli/cmd_image.go
 create mode 100644 internal/cli/cmd_recording.go
 create mode 100644 internal/image/store.go
 create mode 100644 internal/recording/store.go

diff --git a/internal/cli/cmd_image.go b/internal/cli/cmd_image.go
new file mode 100644
index 0000000..3322168
--- /dev/null
+++ b/internal/cli/cmd_image.go
@@ -0,0 +1,123 @@
+package cli
+
+import (
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/image"
+	"github.com/YoooClaw/cli/internal/notif"
+	"github.com/spf13/cobra"
+)
+
+func newImageCmd() *cobra.Command {
+	c := &cobra.Command{Use: "image", Short: "图片管理 🟢"}
+
+	list := &cobra.Command{Use: "list", Short: "列出所有图片", Args: cobra.NoArgs, RunE: run(imageList)}
+	list.Flags().String("status", "", "syncing|synced|sync_failed")
+	list.Flags().String("app", "", "按来源应用过滤")
+	list.Flags().String("client", "", "按 clientLabel 过滤；all 为全部")
+	list.Flags().String("from", "", "created_at 起")
+	list.Flags().String("to", "", "created_at 止")
+	list.Flags().String("limit", "100", "最大返回条数")
+
+	status := &cobra.Command{Use: "status <id>", Short: "查看单张图片详情", Args: cobra.ExactArgs(1), RunE: run(imageStatus)}
+	pathCmd := &cobra.Command{Use: "path <id>", Short: "打印图片本地文件绝对路径", Args: cobra.ExactArgs(1), RunE: run(imagePath)}
+	pathCmd.Flags().Bool("thumbnail", false, "返回缩略图路径（若有）")
+	storagePath := &cobra.Command{Use: "storage-path", Short: "打印图片存储目录绝对路径", Args: cobra.NoArgs, RunE: run(imageStoragePath)}
+	latest := &cobra.Command{Use: "+latest", Short: "展示最新一张图片详情", Args: cobra.NoArgs, RunE: run(imageLatest)}
+
+	c.AddCommand(list, status, pathCmd, storagePath, latest)
+	return c
+}
+
+func imageEntryAsAny(e image.Entry) any { return e }
+
+func imageList(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	items := image.ReadIndex(ctx.Paths.Images)
+	status := flagStr(cmd, "status")
+	client := flagStr(cmd, "client")
+	app := flagStr(cmd, "app")
+	from := flagStr(cmd, "from")
+	to := flagStr(cmd, "to")
+
+	out := make([]image.Entry, 0, len(items))
+	for _, it := range items {
+		if status != "" && it.Status != status {
+			continue
+		}
+		if client != "" && client != "all" && labelOrLegacy2(it.ClientLabel) != client {
+			continue
+		}
+		if app != "" && !notif.MatchesAppFilter(notif.StoredNotification{AppName: it.Metadata.SourceApp}, app) {
+			continue
+		}
+		if from != "" && it.Metadata.CreatedAt < from {
+			continue
+		}
+		if to != "" && it.Metadata.CreatedAt > to {
+			continue
+		}
+		out = append(out, it)
+	}
+	image.SortByCreatedDesc(out)
+	limit := atoiDefault(flagStr(cmd, "limit"), 100)
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	arr := make([]any, 0, len(out))
+	for _, e := range out {
+		arr = append(arr, imageEntryAsAny(e))
+	}
+	return map[string]any{"ok": true, "total": len(out), "images": arr}, nil
+}
+
+func findImage(ctx *clictx.Context, id string) (image.Entry, bool) {
+	for _, it := range image.ReadIndex(ctx.Paths.Images) {
+		if it.ImageID == id {
+			return it, true
+		}
+	}
+	return image.Entry{}, false
+}
+
+func imageStatus(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	e, ok := findImage(ctx, args[0])
+	if !ok {
+		return nil, errs.New(errs.CodeNotFound, "图片不存在："+args[0])
+	}
+	return map[string]any{"ok": true, "image": e}, nil
+}
+
+func imagePath(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	e, ok := findImage(ctx, args[0])
+	if !ok {
+		return nil, errs.New(errs.CodeNotFound, "图片不存在："+args[0])
+	}
+	var rel *string
+	if flagBool(cmd, "thumbnail") {
+		rel = e.Thumbnail
+	} else {
+		rel = e.LocalFile
+	}
+	if e.Status != "synced" || rel == nil || *rel == "" {
+		var lastErr any
+		if e.LastError != nil {
+			lastErr = *e.LastError
+		}
+		return nil, errs.New(errs.CodeImageNotReady, "图片 "+args[0]+" 尚未下载完成",
+			map[string]any{"status": e.Status, "lastError": lastErr})
+	}
+	return map[string]any{"ok": true, "path": image.ResolveFile(ctx.Paths.Images, *rel)}, nil
+}
+
+func imageStoragePath(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return map[string]any{"ok": true, "path": ctx.Paths.Images}, nil
+}
+
+func imageLatest(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	items := image.ReadIndex(ctx.Paths.Images)
+	image.SortByCreatedDesc(items)
+	if len(items) == 0 {
+		return map[string]any{"ok": true, "image": nil}, nil
+	}
+	return map[string]any{"ok": true, "image": items[0]}, nil
+}
diff --git a/internal/cli/cmd_recording.go b/internal/cli/cmd_recording.go
new file mode 100644
index 0000000..5baf5df
--- /dev/null
+++ b/internal/cli/cmd_recording.go
@@ -0,0 +1,256 @@
+package cli
+
+import (
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/prompt"
+	"github.com/YoooClaw/cli/internal/recording"
+	"github.com/spf13/cobra"
+)
+
+func newRecordingCmd() *cobra.Command {
+	c := &cobra.Command{Use: "recording", Short: "录音查询与 ASR 配置 🟢"}
+
+	list := &cobra.Command{Use: "list", Short: "列出所有录音 🟢", Args: cobra.NoArgs, RunE: run(recordingList)}
+	list.Flags().String("status", "", "按传输状态过滤")
+	list.Flags().String("client", "", "按 clientLabel 过滤；all 为全部")
+	status := &cobra.Command{Use: "status <id>", Short: "查看单条录音详情 🟢", Args: cobra.ExactArgs(1), RunE: run(recordingStatusCmd)}
+	storagePath := &cobra.Command{Use: "storage-path", Short: "打印录音存储目录绝对路径 🟢", Args: cobra.NoArgs, RunE: run(recordingStoragePath)}
+
+	setupAsr := &cobra.Command{Use: "setup-asr", Short: "交互式配置 ASR 转写参数 🟢", Args: cobra.NoArgs, RunE: run(recordingSetupAsr)}
+	setupAsr.Flags().String("mode", "", "api | local（默认 api）")
+	setupAsr.Flags().String("api-key", "", "api 模式：可选；留空则用 account ock- key")
+	setupAsr.Flags().String("endpoint", "", "api 模式：自定义 model-proxy 端点")
+	setupAsr.Flags().String("language", "", "api 模式：语言提示，如 zh / en / auto")
+	setupAsr.Flags().String("model", "", "local 模式：Whisper 模型名")
+	setupAsr.Flags().Bool("non-interactive", false, "跳过向导，从参数构造配置")
+
+	events := &cobra.Command{Use: "events", Short: "查询录音状态事件流（JSONL）🟢", Args: cobra.NoArgs, RunE: run(recordingEvents)}
+	events.Flags().String("id", "", "只看某条录音的事件")
+	events.Flags().String("since", "", "回看时间窗，如 10m / 1h / 24h")
+	events.Flags().Bool("watch", false, "持续跟随新事件（本 build 暂返回快照）")
+	events.Flags().String("limit", "200", "返回条数上限")
+
+	latest := &cobra.Command{Use: "+latest", Short: "展示最新一条录音详情", Args: cobra.NoArgs, RunE: run(recordingLatest)}
+
+	c.AddCommand(list, status, storagePath, setupAsr, events, latest)
+	return c
+}
+
+func recToListItem(r recording.Entry) map[string]any {
+	return map[string]any{
+		"id": r.ID, "clientLabel": labelOrLegacy2(r.ClientLabel), "name": r.Metadata.Name,
+		"duration_sec": r.Metadata.DurationSec, "status": r.Status, "file_size_bytes": r.Metadata.FileSizeBytes,
+		"has_audio": r.AudioFile != "", "has_transcript": r.TranscriptFile != "",
+		"created_at": r.Metadata.CreatedAt, "updated_at": r.UpdatedAt, "error": nilIfEmpty(r.LastError),
+	}
+}
+
+func recordingList(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	recs := recording.ReadIndex(ctx.Paths.Recordings)
+	status := flagStr(cmd, "status")
+	client := flagStr(cmd, "client")
+	out := make([]any, 0, len(recs))
+	for _, r := range recs {
+		if status != "" && r.Status != status {
+			continue
+		}
+		if client != "" && client != "all" && labelOrLegacy2(r.ClientLabel) != client {
+			continue
+		}
+		out = append(out, recToListItem(r))
+	}
+	return map[string]any{"ok": true, "total": len(out), "recordings": out}, nil
+}
+
+func findRecording(ctx *clictx.Context, id string) (recording.Entry, bool) {
+	for _, r := range recording.ReadIndex(ctx.Paths.Recordings) {
+		if r.ID == id {
+			return r, true
+		}
+	}
+	return recording.Entry{}, false
+}
+
+func recordingDetail(r recording.Entry) map[string]any {
+	var markers any = r.Metadata.Markers
+	if markers == nil {
+		markers = []any{}
+	}
+	return map[string]any{
+		"id": r.ID, "clientLabel": labelOrLegacy2(r.ClientLabel), "name": r.Metadata.Name,
+		"duration_sec": r.Metadata.DurationSec, "file_size_bytes": r.Metadata.FileSizeBytes,
+		"status": r.Status, "created_at": r.Metadata.CreatedAt, "location": r.Metadata.Location,
+		"markers": markers, "audioFile": nilIfEmpty(r.AudioFile), "srtFile": nilIfEmpty(r.SrtFile),
+		"transcriptDataFile": nilIfEmpty(r.TranscriptDataFile), "transcriptFile": nilIfEmpty(r.TranscriptFile),
+		"summaryFile": nilIfEmpty(r.SummaryFile), "title": nilIfEmpty(r.Title), "error": nilIfEmpty(r.LastError),
+		"ingestedAt": r.IngestedAt, "updatedAt": r.UpdatedAt,
+	}
+}
+
+func recordingStatusCmd(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	r, ok := findRecording(ctx, args[0])
+	if !ok {
+		return nil, errs.New(errs.CodeNotFound, "录音不存在："+args[0])
+	}
+	return map[string]any{"ok": true, "recording": recordingDetail(r)}, nil
+}
+
+func recordingStoragePath(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return map[string]any{"ok": true, "path": ctx.Paths.Recordings}, nil
+}
+
+func recordingLatest(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	recs := recording.ReadIndex(ctx.Paths.Recordings)
+	if len(recs) == 0 {
+		return map[string]any{"ok": true, "recording": nil}, nil
+	}
+	recording.SortByCreatedDesc(recs)
+	return map[string]any{"ok": true, "recording": recordingDetail(recs[0])}, nil
+}
+
+var sinceRE = regexp.MustCompile(`^(\d+)([smhd])$`)
+
+func parseSince(input string) (*time.Time, error) {
+	if input == "" {
+		return nil, nil
+	}
+	m := sinceRE.FindStringSubmatch(strings.TrimSpace(input))
+	if m == nil {
+		return nil, errs.Newf(errs.CodeInvalidArgument, `--since 格式应为 <数字><单位>，单位 s/m/h/d（收到 "%s"）`, input)
+	}
+	n, _ := strconv.Atoi(m[1])
+	unit := map[string]time.Duration{"s": time.Second, "m": time.Minute, "h": time.Hour, "d": 24 * time.Hour}[m[2]]
+	t := time.Now().Add(-time.Duration(n) * unit)
+	return &t, nil
+}
+
+func recordingEvents(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	path := filepath.Join(ctx.Paths.Recordings, "state", "events.jsonl")
+	limit := atoiDefault(flagStr(cmd, "limit"), 200)
+	since, err := parseSince(flagStr(cmd, "since"))
+	if err != nil {
+		return nil, err
+	}
+	id := flagStr(cmd, "id")
+	events := recording.ReadEvents(path)
+	filtered := make([]any, 0, len(events))
+	for _, e := range events {
+		if id != "" && e["recordingId"] != id {
+			continue
+		}
+		if since != nil {
+			tsStr, _ := e["ts"].(string)
+			if ts, ok := parseEventTime(tsStr); !ok || ts.Before(*since) {
+				continue
+			}
+		}
+		filtered = append(filtered, e)
+	}
+	if len(filtered) > limit {
+		filtered = filtered[len(filtered)-limit:]
+	}
+	return map[string]any{"ok": true, "path": path, "total": len(filtered), "events": filtered}, nil
+}
+
+func parseEventTime(s string) (time.Time, bool) {
+	for _, layout := range []string{time.RFC3339Nano, time.RFC3339} {
+		if t, err := time.Parse(layout, s); err == nil {
+			return t, true
+		}
+	}
+	return time.Time{}, false
+}
+
+func recordingSetupAsr(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	mode := strings.ToLower(firstNonEmpty(flagStr(cmd, "mode"), "api"))
+	apiKey := flagStr(cmd, "api-key")
+	endpoint := flagStr(cmd, "endpoint")
+	language := flagStr(cmd, "language")
+	model := flagStr(cmd, "model")
+
+	if !flagBool(cmd, "non-interactive") && prompt.IsInteractive() {
+		var err error
+		if mode, err = prompt.Ask("ASR mode（api / local）", mode); err != nil {
+			return nil, err
+		}
+		mode = strings.ToLower(mode)
+		if mode == "api" {
+			if apiKey, err = prompt.Ask("API key（留空则使用 account ock- key）", apiKey); err != nil {
+				return nil, err
+			}
+			if endpoint, err = prompt.Ask("model-proxy endpoint（留空走默认）", endpoint); err != nil {
+				return nil, err
+			}
+			if language, err = prompt.Ask("语言提示（zh / en / auto）", firstNonEmpty(language, "auto")); err != nil {
+				return nil, err
+			}
+		} else if mode == "local" {
+			if model, err = prompt.Ask("Whisper 模型（留空走推荐值）", model); err != nil {
+				return nil, err
+			}
+		}
+	}
+	if mode != "api" && mode != "local" {
+		return nil, errs.Newf(errs.CodeInvalidArgument, `--mode 必须是 api 或 local（收到 "%s"）`, mode)
+	}
+
+	cfg := buildAsrConfig(mode, apiKey, endpoint, language, model)
+	if err := fsutil.EnsureDir(ctx.Paths.Recordings, fsutil.DirMode); err != nil {
+		return nil, err
+	}
+	path := filepath.Join(ctx.Paths.Recordings, "asr-config.json")
+	if err := fsutil.WriteJSON(path, cfg, fsutil.ConfigFileMode); err != nil {
+		return nil, err
+	}
+	var keyConfigured any = "n/a"
+	if mode == "api" {
+		if apiKey != "" {
+			keyConfigured = true
+		} else {
+			keyConfigured = "fallback-to-account"
+		}
+	}
+	return map[string]any{"ok": true, "path": path, "mode": mode, "keyConfigured": keyConfigured}, nil
+}
+
+func buildAsrConfig(mode, apiKey, endpoint, language, model string) map[string]any {
+	if mode == "api" {
+		api := map[string]any{}
+		if apiKey != "" {
+			api["apiKey"] = apiKey
+		}
+		if endpoint != "" {
+			api["endpoint"] = endpoint
+		}
+		if language != "" {
+			api["language"] = language
+		}
+		if len(api) > 0 {
+			return map[string]any{"mode": mode, "api": api}
+		}
+		return map[string]any{"mode": mode}
+	}
+	local := map[string]any{}
+	if model != "" {
+		local["model"] = model
+	}
+	if len(local) > 0 {
+		return map[string]any{"mode": mode, "local": local}
+	}
+	return map[string]any{"mode": mode}
+}
+
+func labelOrLegacy2(label string) string {
+	if label == "" {
+		return "legacy"
+	}
+	return label
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 97fd11f..a32bb5f 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -32,6 +32,8 @@ func newRootCmd() *cobra.Command {
 		newAuthCmd(),
 		newDaemonCmd(),
 		newNotificationCmd(),
+		newRecordingCmd(),
+		newImageCmd(),
 		newLogCmd(),
 		newMigrateCmd(),
 		newUpdateCmd(),
diff --git a/internal/image/store.go b/internal/image/store.go
new file mode 100644
index 0000000..22f5939
--- /dev/null
+++ b/internal/image/store.go
@@ -0,0 +1,65 @@
+// Package image 读取图片索引（images/index.json），对齐 TS 版 src/image/storage.ts。
+//
+// 元数据与同步状态由 daemon 图片通道写入；CLI 查询纯读，不需要 daemon。
+package image
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// Metadata 是图片元数据。
+type Metadata struct {
+	OssImageURL string `json:"oss_image_url"`
+	CreatedAt   string `json:"created_at"`
+	MimeType    string `json:"mime_type,omitempty"`
+	Width       int    `json:"width,omitempty"`
+	Height      int    `json:"height,omitempty"`
+	SizeBytes   int64  `json:"size_bytes,omitempty"`
+	SourceApp   string `json:"source_app,omitempty"`
+	Caption     string `json:"caption,omitempty"`
+}
+
+// Entry 是一条图片索引项。
+type Entry struct {
+	ImageID     string   `json:"imageId"`
+	ClientLabel string   `json:"clientLabel,omitempty"`
+	Metadata    Metadata `json:"metadata"`
+	LocalFile   *string  `json:"localFile,omitempty"`
+	Thumbnail   *string  `json:"thumbnail,omitempty"`
+	Status      string   `json:"status"`
+	LastError   *string  `json:"lastError,omitempty"`
+	SyncedAt    *string  `json:"syncedAt,omitempty"`
+}
+
+// ReadIndex 读取 images/index.json 的 images[]；不存在返回空。
+func ReadIndex(imagesDir string) []Entry {
+	raw, err := os.ReadFile(filepath.Join(imagesDir, "index.json"))
+	if err != nil {
+		return nil
+	}
+	var wrapper struct {
+		Images []Entry `json:"images"`
+	}
+	if json.Unmarshal(raw, &wrapper) != nil {
+		return nil
+	}
+	return wrapper.Images
+}
+
+// ResolveFile 把相对路径解析为绝对路径。
+func ResolveFile(imagesDir, relative string) string {
+	if filepath.IsAbs(relative) {
+		return relative
+	}
+	return filepath.Join(imagesDir, relative)
+}
+
+// SortByCreatedDesc 按 created_at 倒序排序。
+func SortByCreatedDesc(entries []Entry) {
+	sort.SliceStable(entries, func(i, j int) bool {
+		return entries[i].Metadata.CreatedAt > entries[j].Metadata.CreatedAt
+	})
+}
diff --git a/internal/recording/store.go b/internal/recording/store.go
new file mode 100644
index 0000000..4b322fc
--- /dev/null
+++ b/internal/recording/store.go
@@ -0,0 +1,84 @@
+// Package recording 读取录音索引（recordings/index.json）与状态事件流
+// （recordings/state/events.jsonl），对齐 TS 版 cli helpers + commands/recording.ts。
+package recording
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// Metadata 是录音元数据（index.json entry.metadata）。
+type Metadata struct {
+	Name          string  `json:"name"`
+	DurationSec   float64 `json:"duration_sec"`
+	FileSizeBytes int64   `json:"file_size_bytes"`
+	CreatedAt     string  `json:"created_at"`
+	Status        string  `json:"transfer_status"`
+	Location      any     `json:"location,omitempty"`
+	Markers       any     `json:"markers,omitempty"`
+}
+
+// Entry 是一条录音索引项。
+type Entry struct {
+	ID                 string   `json:"id"`
+	ClientLabel        string   `json:"clientLabel,omitempty"`
+	Metadata           Metadata `json:"metadata"`
+	Status             string   `json:"status"`
+	AudioFile          string   `json:"audioFile,omitempty"`
+	SrtFile            string   `json:"srtFile,omitempty"`
+	TranscriptDataFile string   `json:"transcriptDataFile,omitempty"`
+	TranscriptFile     string   `json:"transcriptFile,omitempty"`
+	SummaryFile        string   `json:"summaryFile,omitempty"`
+	Title              string   `json:"title,omitempty"`
+	LastError          string   `json:"lastError,omitempty"`
+	IngestedAt         string   `json:"ingestedAt"`
+	UpdatedAt          string   `json:"updatedAt"`
+}
+
+// ReadIndex 读取 recordings/index.json 的 recordings[]；目录/文件不存在返回空。
+func ReadIndex(recordingsDir string) []Entry {
+	raw, err := os.ReadFile(filepath.Join(recordingsDir, "index.json"))
+	if err != nil {
+		return nil
+	}
+	var wrapper struct {
+		Recordings []Entry `json:"recordings"`
+	}
+	if json.Unmarshal(raw, &wrapper) != nil {
+		return nil
+	}
+	return wrapper.Recordings
+}
+
+// SortByCreatedDesc 按 created_at 倒序排序。
+func SortByCreatedDesc(entries []Entry) {
+	sort.SliceStable(entries, func(i, j int) bool {
+		return entries[i].Metadata.CreatedAt > entries[j].Metadata.CreatedAt
+	})
+}
+
+// Event 是录音状态事件（events.jsonl 一行），保留全部原始字段。
+type Event = map[string]any
+
+// ReadEvents 读取 events.jsonl；损坏行跳过。
+func ReadEvents(eventsPath string) []Event {
+	raw, err := os.ReadFile(eventsPath)
+	if err != nil {
+		return nil
+	}
+	var out []Event
+	for _, line := range strings.Split(string(raw), "\n") {
+		t := strings.TrimSpace(line)
+		if t == "" {
+			continue
+		}
+		var e Event
+		if json.Unmarshal([]byte(t), &e) == nil {
+			out = append(out, e)
+		}
+	}
+	return out
+}

From 96fe9ab9b1b17f3e1426cec87e7bb9da8435e8b1 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 17:18:32 +0800
Subject: [PATCH 05/13] =?UTF-8?q?feat(go):=20Phase=202=20=E2=80=94=20monit?=
 =?UTF-8?q?or=20=E7=AB=AF=E5=88=B0=E7=AB=AF=20+=20tunnel/gateway/api=20?=
 =?UTF-8?q?=E4=BB=A3=E7=90=86=E5=91=BD=E4=BB=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- internal/monitor：state/monitors.json 定义 CRUD（list/get/create/delete/setEnabled）
- daemon/server_services：/monitors（GET/POST/DELETE/enable|disable）+ /tunnel/*
  （standalone-http 语义；+test 走本地 echo ingest 回环）
- cli daemon-services 代理命令：
  monitor list/show/create/delete/enable/disable（经 daemon /monitors）
  tunnel status/reconnect/+test、gateway test、api <method> <path>（raw 直通）

验证（daemon 在跑）：monitor 全 CRUD、gateway test（probe ingested=1）、
tunnel status standalone、tunnel +test echo 回环 ok、api GET /daemon/status 直通。

light/lightrule 待 light 硬件 vendor 端口移植后接入（下一focused pass）。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/cli/cmd_daemon_services.go | 269 ++++++++++++++++++++++++++++
 internal/cli/cmd_update.go          |   6 +-
 internal/cli/root.go                |   4 +
 internal/daemon/server.go           |   4 +
 internal/daemon/server_services.go  | 107 +++++++++++
 internal/monitor/store.go           | 127 +++++++++++++
 6 files changed, 514 insertions(+), 3 deletions(-)
 create mode 100644 internal/cli/cmd_daemon_services.go
 create mode 100644 internal/daemon/server_services.go
 create mode 100644 internal/monitor/store.go

diff --git a/internal/cli/cmd_daemon_services.go b/internal/cli/cmd_daemon_services.go
new file mode 100644
index 0000000..6d31b56
--- /dev/null
+++ b/internal/cli/cmd_daemon_services.go
@@ -0,0 +1,269 @@
+package cli
+
+import (
+	"encoding/json"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/daemon"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/prompt"
+	"github.com/spf13/cobra"
+)
+
+// daemonProxy 是依赖 daemon 的命令前置：确保 daemon 在运行并返回 client。
+func daemonProxy(ctx *clictx.Context) (*daemon.Client, error) {
+	if err := daemon.AssertRunning(ctx.Paths); err != nil {
+		return nil, err
+	}
+	return daemon.NewClient(ctx.Paths), nil
+}
+
+func parseJSONArg(raw, label string) (any, error) {
+	if raw == "" {
+		return nil, nil
+	}
+	var v any
+	if json.Unmarshal([]byte(raw), &v) != nil {
+		return nil, errs.New(errs.CodeInvalidArgument, label+" 不是合法 JSON")
+	}
+	return v, nil
+}
+
+// ── tunnel ──
+
+func newTunnelCmd() *cobra.Command {
+	c := &cobra.Command{Use: "tunnel", Short: "Relay 隧道 🟡"}
+	status := &cobra.Command{Use: "status", Short: "查询 Relay 连接状态", Args: cobra.NoArgs, RunE: run(tunnelStatus)}
+	status.Flags().String("client", "", "只看指定 clientLabel；all 为全部")
+	reconnect := &cobra.Command{Use: "reconnect", Short: "强制重连", Args: cobra.NoArgs, RunE: run(tunnelReconnect)}
+	reconnect.Flags().String("client", "", "只重连指定 clientLabel")
+	test := &cobra.Command{Use: "+test", Short: "daemon 本地 ingest + 鉴权自检（echo 回环）", Args: cobra.NoArgs, RunE: run(tunnelTest)}
+	test.Flags().String("client", "", "用指定 clientLabel 的 api-key 做回环写入")
+	c.AddCommand(status, reconnect, test)
+	return c
+}
+
+func tunnelStatus(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	path := "/tunnel/status"
+	if client := flagStr(cmd, "client"); client != "" {
+		path += "?client=" + url.QueryEscape(client)
+	}
+	_, body, err := c.Request("GET", path, nil)
+	return body, err
+}
+
+func tunnelReconnect(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	var reqBody any
+	if client := flagStr(cmd, "client"); client != "" {
+		reqBody = map[string]any{"client": client}
+	}
+	_, body, err := c.Request("POST", "/tunnel/reconnect", reqBody)
+	return body, err
+}
+
+func tunnelTest(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	var reqBody any
+	if client := flagStr(cmd, "client"); client != "" {
+		reqBody = map[string]any{"client": client}
+	}
+	_, body, err := c.Request("POST", "/tunnel/test", reqBody)
+	return body, err
+}
+
+// ── monitor ──
+
+func newMonitorCmd() *cobra.Command {
+	c := &cobra.Command{Use: "monitor", Short: "定时通知监控任务 🟡"}
+	list := &cobra.Command{Use: "list", Short: "列出所有监控任务", Args: cobra.NoArgs, RunE: run(monitorList)}
+	show := &cobra.Command{Use: "show <name>", Short: "查看监控任务详情", Args: cobra.ExactArgs(1), RunE: run(monitorShow)}
+	create := &cobra.Command{Use: "create <name>", Short: "创建监控任务（cron 驱动）", Args: cobra.ExactArgs(1), RunE: run(monitorCreate)}
+	create.Flags().String("description", "", "任务描述（必填）")
+	create.Flags().String("match-rules", "", "匹配规则 JSON（必填）")
+	create.Flags().String("schedule", "", "cron 表达式（必填）")
+	del := &cobra.Command{Use: "delete <name>", Short: "删除监控任务（--yes）", Args: cobra.ExactArgs(1), RunE: run(monitorDelete)}
+	del.Flags().Bool("yes", false, "跳过确认")
+	enable := &cobra.Command{Use: "enable <name>", Short: "启用监控任务", Args: cobra.ExactArgs(1), RunE: run(monitorEnable)}
+	disable := &cobra.Command{Use: "disable <name>", Short: "暂停监控任务", Args: cobra.ExactArgs(1), RunE: run(monitorDisable)}
+	c.AddCommand(list, show, create, del, enable, disable)
+	return c
+}
+
+func monitorList(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("GET", "/monitors", nil)
+	return body, err
+}
+
+func monitorShow(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("GET", "/monitors", nil)
+	if err != nil {
+		return nil, err
+	}
+	if m, ok := body.(map[string]any); ok {
+		if list, ok := m["monitors"].([]any); ok {
+			for _, item := range list {
+				if mon, ok := item.(map[string]any); ok && mon["name"] == args[0] {
+					return map[string]any{"ok": true, "monitor": mon}, nil
+				}
+			}
+		}
+	}
+	return nil, errs.New(errs.CodeNotFound, "监控任务不存在："+args[0])
+}
+
+func monitorCreate(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	desc, sched, mr := flagStr(cmd, "description"), flagStr(cmd, "schedule"), flagStr(cmd, "match-rules")
+	if desc == "" || mr == "" || sched == "" {
+		return nil, errs.New(errs.CodeInvalidArgument, "--description / --match-rules / --schedule 均必填")
+	}
+	matchRules, err := parseJSONArg(mr, "--match-rules")
+	if err != nil {
+		return nil, err
+	}
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("POST", "/monitors", map[string]any{
+		"name": args[0], "description": desc, "matchRules": matchRules, "schedule": sched,
+	})
+	return body, err
+}
+
+func monitorDelete(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	if !flagBool(cmd, "yes") {
+		ok, err := prompt.Confirm("确认删除监控任务 `"+args[0]+"`？", false)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			return nil, errs.New(errs.CodeConfirmationRequired, "已取消")
+		}
+	}
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("DELETE", "/monitors/"+url.PathEscape(args[0]), nil)
+	return body, err
+}
+
+func monitorEnable(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	return monitorToggle(ctx, args[0], "enable")
+}
+
+func monitorDisable(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	return monitorToggle(ctx, args[0], "disable")
+}
+
+func monitorToggle(ctx *clictx.Context, name, action string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("POST", "/monitors/"+url.PathEscape(name)+"/"+action, nil)
+	return body, err
+}
+
+// ── gateway test ──
+
+func newGatewayCmd() *cobra.Command {
+	c := &cobra.Command{Use: "gateway", Short: "协议自检 🟢/🟡"}
+	test := &cobra.Command{Use: "test", Short: "模拟手机端调 daemon /notifications，验证本地连通与鉴权 🟡", Args: cobra.NoArgs, RunE: run(gatewayTest)}
+	test.Flags().String("from-phone-ip", "", "模拟来源 IP")
+	test.Flags().Bool("via-relay", false, "复用 tunnel +test 本地回环路径")
+	c.AddCommand(test)
+	return c
+}
+
+func gatewayTest(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if flagBool(cmd, "via-relay") {
+		_, body, err := c.Request("POST", "/tunnel/test", nil)
+		return map[string]any{"ok": true, "viaRelay": true, "result": body}, err
+	}
+	probe := map[string]any{"notifications": []any{map[string]any{
+		"id": "gwtest_" + strconv.FormatInt(time.Now().UnixMilli(), 10), "app": "yoooclaw.gatewaytest",
+		"title": "gateway test", "body": "probe", "timestamp": time.Now().Format(time.RFC3339),
+	}}}
+	status, body, err := c.Request("POST", "/notifications", probe)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"ok": status >= 200 && status < 300, "fromPhoneIp": nilIfEmpty(flagStr(cmd, "from-phone-ip")),
+		"status": status, "response": body,
+	}, nil
+}
+
+// ── raw api ──
+
+func newAPICmd() *cobra.Command {
+	c := &cobra.Command{Use: "api <method> <path>", Short: "Raw HTTP escape hatch 🟡", Args: cobra.ExactArgs(2), RunE: run(apiRaw)}
+	c.Flags().String("data", "", "请求体（@file 读文件、- 读 stdin）")
+	c.Flags().StringArray("header", nil, "追加 header（可重复）")
+	return c
+}
+
+func apiRaw(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	method, path := strings.ToUpper(args[0]), args[1]
+	var data any
+	if d := flagStr(cmd, "data"); d != "" {
+		var raw string
+		switch {
+		case d == "-":
+			s, err := prompt.ReadStdin()
+			if err != nil {
+				return nil, err
+			}
+			raw = s
+		case strings.HasPrefix(d, "@"):
+			b, err := os.ReadFile(d[1:])
+			if err != nil {
+				return nil, errs.New(errs.CodeInvalidArgument, "无法读取文件："+d[1:])
+			}
+			raw = string(b)
+		default:
+			raw = d
+		}
+		if json.Unmarshal([]byte(raw), &data) != nil {
+			data = raw
+		}
+	}
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	status, body, err := c.Request(method, path, data)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": status >= 200 && status < 300, "status": status, "body": body}, nil
+}
diff --git a/internal/cli/cmd_update.go b/internal/cli/cmd_update.go
index f66acee..3c78276 100644
--- a/internal/cli/cmd_update.go
+++ b/internal/cli/cmd_update.go
@@ -91,7 +91,7 @@ func updateSelf(_ *clictx.Context, cmd *cobra.Command, _ []string) (any, error)
 	ctxReq, cancel := context.WithTimeout(context.Background(), 8*time.Second)
 	defer cancel()
 
-	req, err := http.NewRequestWithContext(ctxReq, http.MethodGet, updateRegistry+"/"+url(updatePackage), nil)
+	req, err := http.NewRequestWithContext(ctxReq, http.MethodGet, updateRegistry+"/"+encodePkgName(updatePackage), nil)
 	if err != nil {
 		return nil, errs.New(errs.CodeNetworkError, "构造 npm 请求失败")
 	}
@@ -133,7 +133,7 @@ func updateSelf(_ *clictx.Context, cmd *cobra.Command, _ []string) (any, error)
 	}, nil
 }
 
-// url 对 @scope/name 做最简 path 编码（@ 与 / 需转义）。
-func url(pkg string) string {
+// encodePkgName 对 @scope/name 做最简 path 编码（/ 转义）。
+func encodePkgName(pkg string) string {
 	return strings.ReplaceAll(pkg, "/", "%2F")
 }
diff --git a/internal/cli/root.go b/internal/cli/root.go
index a32bb5f..73128f5 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -34,6 +34,10 @@ func newRootCmd() *cobra.Command {
 		newNotificationCmd(),
 		newRecordingCmd(),
 		newImageCmd(),
+		newMonitorCmd(),
+		newTunnelCmd(),
+		newGatewayCmd(),
+		newAPICmd(),
 		newLogCmd(),
 		newMigrateCmd(),
 		newUpdateCmd(),
diff --git a/internal/daemon/server.go b/internal/daemon/server.go
index b666d65..e5388f7 100644
--- a/internal/daemon/server.go
+++ b/internal/daemon/server.go
@@ -173,6 +173,10 @@ func (s *server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		s.handleIngest(w, r, authCtx, "notifications")
 	case path == "/gateway/notifications.push" && r.Method == http.MethodPost:
 		s.handleIngest(w, r, authCtx, "items")
+	case path == "/monitors" || strings.HasPrefix(path, "/monitors/"):
+		s.handleMonitors(w, r, path)
+	case strings.HasPrefix(path, "/tunnel/"):
+		s.handleTunnel(w, r, path)
 	default:
 		writeJSON(w, 404, map[string]any{"ok": false, "error": map[string]any{"code": errs.CodeNotFound, "message": "未知路径：" + path}})
 	}
diff --git a/internal/daemon/server_services.go b/internal/daemon/server_services.go
new file mode 100644
index 0000000..74d6e16
--- /dev/null
+++ b/internal/daemon/server_services.go
@@ -0,0 +1,107 @@
+package daemon
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/monitor"
+	"github.com/YoooClaw/cli/internal/notif"
+)
+
+// handleMonitors 处理 /monitors 与 /monitors/<name>[/enable|disable]。
+func (s *server) handleMonitors(w http.ResponseWriter, r *http.Request, path string) {
+	p := s.ctx.Paths
+	switch {
+	case path == "/monitors" && r.Method == http.MethodGet:
+		writeJSON(w, 200, map[string]any{"ok": true, "monitors": monitor.List(p)})
+	case path == "/monitors" && r.Method == http.MethodPost:
+		var body struct {
+			Name        string `json:"name"`
+			Description string `json:"description"`
+			MatchRules  any    `json:"matchRules"`
+			Schedule    string `json:"schedule"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		task, err := monitor.Create(p, monitor.CreateInput{
+			Name: body.Name, Description: body.Description, MatchRules: body.MatchRules, Schedule: body.Schedule,
+		})
+		if err != nil {
+			writeJSON(w, 400, errBody("INVALID_PARAMS", err.Error()))
+			return
+		}
+		writeJSON(w, 200, map[string]any{"ok": true, "monitor": task})
+	case strings.HasPrefix(path, "/monitors/") && r.Method == http.MethodDelete:
+		name := decodePathSeg(path[len("/monitors/"):])
+		deleted, _ := monitor.Delete(p, name)
+		writeJSON(w, 200, map[string]any{"ok": true, "deleted": deleted})
+	case strings.HasPrefix(path, "/monitors/") && r.Method == http.MethodPost:
+		// /monitors/<name>/<enable|disable>
+		rest := path[len("/monitors/"):]
+		idx := strings.LastIndex(rest, "/")
+		if idx < 0 {
+			writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
+			return
+		}
+		name := decodePathSeg(rest[:idx])
+		enabled := rest[idx+1:] == "enable"
+		ok, _ := monitor.SetEnabled(p, name, enabled)
+		writeJSON(w, 200, map[string]any{"ok": ok, "name": name, "enabled": enabled})
+	default:
+		writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
+	}
+}
+
+// handleTunnel 处理 /tunnel/*。本 build 无 Relay 隧道（Phase 3），返回 standalone 语义。
+func (s *server) handleTunnel(w http.ResponseWriter, r *http.Request, path string) {
+	note := "Relay 隧道未实现（Phase 3）；当前仅直连 HTTP"
+	switch path {
+	case "/tunnel/status":
+		writeJSON(w, 200, map[string]any{
+			"ok": true, "mode": "standalone-http", "credentialMode": s.credentialSet.Mode,
+			"connected": false, "relayUrl": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
+			"note": note, "tunnels": []any{},
+		})
+	case "/tunnel/reconnect":
+		writeJSON(w, 200, map[string]any{"ok": true, "mode": "standalone-http", "reconnected": false, "note": note})
+	case "/tunnel/test":
+		// 回环自检：直接本地 ingest 一条 echo 通知。
+		_ = r
+		res := s.storage.Ingest([]notif.RawNotification{{
+			ID: "echo_local_" + time.Now().Format("20060102150405"), App: "yoooclaw.selftest",
+			Title: "tunnel +test", Body: "echo", Timestamp: time.Now().Format(time.RFC3339),
+		}}, "local")
+		ok := res.Ingested > 0 || res.DedupedByID > 0 || res.DedupedByContent > 0
+		writeJSON(w, 200, map[string]any{"ok": ok, "mode": "standalone-http", "loopback": map[string]any{"ok": ok}})
+	default:
+		writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
+	}
+}
+
+func decodeBody(w http.ResponseWriter, r *http.Request, out any) bool {
+	data, err := io.ReadAll(r.Body)
+	if err != nil {
+		writeJSON(w, 400, errBody("INVALID_PARAMS", "读取请求体失败"))
+		return false
+	}
+	if len(data) == 0 {
+		return true
+	}
+	if json.Unmarshal(data, out) != nil {
+		writeJSON(w, 400, errBody("INVALID_PARAMS", "请求体不是合法 JSON"))
+		return false
+	}
+	return true
+}
+
+func decodePathSeg(seg string) string {
+	if decoded, err := url.PathUnescape(seg); err == nil {
+		return decoded
+	}
+	return seg
+}
diff --git a/internal/monitor/store.go b/internal/monitor/store.go
new file mode 100644
index 0000000..a6dc6d9
--- /dev/null
+++ b/internal/monitor/store.go
@@ -0,0 +1,127 @@
+// Package monitor 持久化监控任务定义（state/monitors.json）。
+//
+// 本 build 负责定义 CRUD 与启用状态；cron 实时触发为后续迭代。
+package monitor
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/paths"
+)
+
+// Task 是一条监控任务。
+type Task struct {
+	Name        string  `json:"name"`
+	Description string  `json:"description"`
+	MatchRules  any     `json:"matchRules"`
+	Schedule    string  `json:"schedule"`
+	Enabled     bool    `json:"enabled"`
+	CreatedAt   string  `json:"createdAt"`
+	UpdatedAt   string  `json:"updatedAt"`
+	LastRunAt   *string `json:"lastRunAt"`
+	LastResult  any     `json:"lastResult"`
+}
+
+// CreateInput 是创建任务的入参。
+type CreateInput struct {
+	Name        string
+	Description string
+	MatchRules  any
+	Schedule    string
+}
+
+func storePath(p paths.Paths) string {
+	return filepath.Join(p.State, "monitors.json")
+}
+
+// List 列出全部任务；不存在返回空。
+func List(p paths.Paths) []Task {
+	raw, err := os.ReadFile(storePath(p))
+	if err != nil {
+		return nil
+	}
+	var wrapper struct {
+		Monitors []Task `json:"monitors"`
+	}
+	if json.Unmarshal(raw, &wrapper) != nil {
+		return nil
+	}
+	return wrapper.Monitors
+}
+
+func save(p paths.Paths, monitors []Task) error {
+	if err := fsutil.EnsureDir(p.State, fsutil.DirMode); err != nil {
+		return err
+	}
+	return fsutil.WriteJSON(storePath(p), map[string]any{"monitors": monitors}, fsutil.ConfigFileMode)
+}
+
+// Get 按名查找任务。
+func Get(p paths.Paths, name string) (Task, bool) {
+	for _, m := range List(p) {
+		if m.Name == name {
+			return m, true
+		}
+	}
+	return Task{}, false
+}
+
+// Create 新建任务。
+func Create(p paths.Paths, in CreateInput) (Task, error) {
+	if in.Name == "" || in.Description == "" || in.Schedule == "" || in.MatchRules == nil {
+		return Task{}, errors.New("name / description / matchRules / schedule 均必填")
+	}
+	monitors := List(p)
+	for _, m := range monitors {
+		if m.Name == in.Name {
+			return Task{}, errors.New("监控任务已存在：" + in.Name)
+		}
+	}
+	now := time.Now().UTC().Format(time.RFC3339)
+	task := Task{
+		Name: in.Name, Description: in.Description, MatchRules: in.MatchRules, Schedule: in.Schedule,
+		Enabled: true, CreatedAt: now, UpdatedAt: now,
+	}
+	monitors = append(monitors, task)
+	if err := save(p, monitors); err != nil {
+		return Task{}, err
+	}
+	return task, nil
+}
+
+// Delete 删除任务；返回是否删除。
+func Delete(p paths.Paths, name string) (bool, error) {
+	monitors := List(p)
+	next := monitors[:0]
+	for _, m := range monitors {
+		if m.Name != name {
+			next = append(next, m)
+		}
+	}
+	if len(next) == len(monitors) {
+		return false, nil
+	}
+	return true, save(p, next)
+}
+
+// SetEnabled 设置启用状态；返回是否命中。
+func SetEnabled(p paths.Paths, name string, enabled bool) (bool, error) {
+	monitors := List(p)
+	found := false
+	for i := range monitors {
+		if monitors[i].Name == name {
+			monitors[i].Enabled = enabled
+			monitors[i].UpdatedAt = time.Now().UTC().Format(time.RFC3339)
+			found = true
+		}
+	}
+	if !found {
+		return false, nil
+	}
+	return true, save(p, monitors)
+}

From 4ac30b6e2e4ccc676b4c0c03fb1e7f4bc4755ff8 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 17:33:33 +0800
Subject: [PATCH 06/13] =?UTF-8?q?feat(go):=20Phase=202=20=E2=80=94=20sync?=
 =?UTF-8?q?=20=E9=80=9A=E7=9F=A5=E5=90=8C=E6=AD=A5=20checkpoint=20?=
 =?UTF-8?q?=E5=8D=8F=E8=AE=AE=EF=BC=88scan/fetch/commit=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

移植 src/notification/sync.ts：日期级 .checkpoint.json 消费进度，
scan 扫描待同步、fetch 按批快照（SyncFetchLimit=300 + --max-end-index）、
commit 推进进度（exact-end-index / legacy-batch-limit 两模式，含回退/越界/
跳批校验）。复用 notif 包既有 listDateKeys/readDateFile，纯本地无 daemon。
全绿 + 5 平台交叉编译。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/cli/cmd_sync.go |  54 ++++++++++
 internal/cli/root.go     |   1 +
 internal/notif/sync.go   | 208 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 263 insertions(+)
 create mode 100644 internal/cli/cmd_sync.go
 create mode 100644 internal/notif/sync.go

diff --git a/internal/cli/cmd_sync.go b/internal/cli/cmd_sync.go
new file mode 100644
index 0000000..b712cf1
--- /dev/null
+++ b/internal/cli/cmd_sync.go
@@ -0,0 +1,54 @@
+package cli
+
+import (
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/notif"
+	"github.com/spf13/cobra"
+)
+
+func newSyncCmd() *cobra.Command {
+	c := &cobra.Command{Use: "sync", Short: "通知同步给记忆系统 🟢"}
+
+	scan := &cobra.Command{
+		Use: "scan", Short: "扫描未处理通知，返回各日期待同步摘要",
+		Args: cobra.NoArgs, RunE: run(syncScan),
+	}
+
+	fetch := &cobra.Command{
+		Use: "fetch", Short: "获取指定日期未处理通知详情",
+		Args: cobra.NoArgs, RunE: run(syncFetch),
+	}
+	fetch.Flags().String("date", "", "目标日期（必填，YYYY-MM-DD）")
+	fetch.Flags().String("max-end-index", "", "本次快照允许读取的最大 endIndex")
+
+	commit := &cobra.Command{
+		Use: "commit", Short: "标记指定日期当前批次处理完成",
+		Args: cobra.NoArgs, RunE: run(syncCommit),
+	}
+	commit.Flags().String("date", "", "目标日期（必填，YYYY-MM-DD）")
+	commit.Flags().String("end-index", "", "本批次 fetch 返回的 endIndex")
+
+	c.AddCommand(scan, fetch, commit)
+	return c
+}
+
+func syncScan(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return notif.ScanSync(ctx.Paths.Notifications), nil
+}
+
+func syncFetch(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	date := flagStr(cmd, "date")
+	if date == "" {
+		return nil, errs.New(errs.CodeInvalidArgument, "--date 必填（YYYY-MM-DD）")
+	}
+	return notif.FetchSync(ctx.Paths.Notifications, date, flagStr(cmd, "max-end-index"))
+}
+
+func syncCommit(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	date := flagStr(cmd, "date")
+	if date == "" {
+		return nil, errs.New(errs.CodeInvalidArgument, "--date 必填（YYYY-MM-DD）")
+	}
+	return notif.CommitSync(ctx.Paths.Notifications, date, flagStr(cmd, "end-index"))
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 73128f5..aa4abcf 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -32,6 +32,7 @@ func newRootCmd() *cobra.Command {
 		newAuthCmd(),
 		newDaemonCmd(),
 		newNotificationCmd(),
+		newSyncCmd(),
 		newRecordingCmd(),
 		newImageCmd(),
 		newMonitorCmd(),
diff --git a/internal/notif/sync.go b/internal/notif/sync.go
new file mode 100644
index 0000000..1f5a4a5
--- /dev/null
+++ b/internal/notif/sync.go
@@ -0,0 +1,208 @@
+package notif
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strconv"
+
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+// SyncFetchLimit 单批 fetch 返回上限（对齐 TS SYNC_FETCH_LIMIT）。
+const SyncFetchLimit = 300
+
+// checkpointEntry 是每个日期的消费进度（已处理到的最大下标）。
+type checkpointEntry struct {
+	LastIndex int `json:"lastIndex"`
+}
+
+func checkpointPath(dir string) string {
+	return filepath.Join(dir, ".checkpoint.json")
+}
+
+// readCheckpoint 读取 checkpoint；不存在 / 损坏时回退为空表（对齐 TS 容错语义）。
+func readCheckpoint(dir string) map[string]checkpointEntry {
+	out := map[string]checkpointEntry{}
+	raw, err := os.ReadFile(checkpointPath(dir))
+	if err != nil {
+		return out
+	}
+	if json.Unmarshal(raw, &out) != nil {
+		return map[string]checkpointEntry{}
+	}
+	return out
+}
+
+func writeCheckpoint(dir string, data map[string]checkpointEntry) error {
+	return fsutil.WriteJSON(checkpointPath(dir), data, fsutil.ConfigFileMode)
+}
+
+// lastIndexFor 返回某日期的 checkpoint 进度，无记录返回 -1。
+func lastIndexFor(checkpoint map[string]checkpointEntry, dateKey string) int {
+	if e, ok := checkpoint[dateKey]; ok {
+		return e.LastIndex
+	}
+	return -1
+}
+
+func parseIndexOption(raw, label string) (int, error) {
+	n, err := strconv.Atoi(raw)
+	if err != nil || n < 0 || strconv.Itoa(n) != raw {
+		return 0, errs.Newf(errs.CodeInvalidArgument, "%s 必须是非负整数", label)
+	}
+	return n, nil
+}
+
+// SyncPending 是 scan 返回的单个日期待同步摘要。
+type SyncPending struct {
+	Date       string `json:"date"`
+	Count      int    `json:"count"`
+	StartIndex int    `json:"startIndex"`
+}
+
+// ScanSync 扫描各日期未处理通知，返回待同步摘要。
+func ScanSync(dir string) map[string]any {
+	checkpoint := readCheckpoint(dir)
+	pending := []SyncPending{}
+	totalPending := 0
+	for _, dateKey := range listDateKeys(dir) {
+		items := readDateFile(dir, dateKey)
+		lastIndex := lastIndexFor(checkpoint, dateKey)
+		unprocessed := len(items) - (lastIndex + 1)
+		if unprocessed > 0 {
+			pending = append(pending, SyncPending{Date: dateKey, Count: unprocessed, StartIndex: lastIndex + 1})
+			totalPending += unprocessed
+		}
+	}
+	return map[string]any{"ok": true, "pending": pending, "totalPending": totalPending}
+}
+
+// FetchSync 返回指定日期未处理通知的一批快照（不推进 checkpoint）。
+func FetchSync(dir, date, maxEndIndexRaw string) (map[string]any, error) {
+	items := readDateFile(dir, date)
+	if len(items) == 0 {
+		return nil, errs.Newf(errs.CodeNotFound, "日期 %s 无通知数据", date)
+	}
+	checkpoint := readCheckpoint(dir)
+	lastIndex := lastIndexFor(checkpoint, date)
+	startIndex := lastIndex + 1
+
+	maxEndIndex := len(items) - 1
+	if maxEndIndexRaw != "" {
+		n, err := parseIndexOption(maxEndIndexRaw, "--max-end-index")
+		if err != nil {
+			return nil, err
+		}
+		if n < maxEndIndex {
+			maxEndIndex = n
+		}
+	}
+
+	snapshotEndExclusive := startIndex
+	if maxEndIndex+1 > snapshotEndExclusive {
+		snapshotEndExclusive = maxEndIndex + 1
+	}
+	unprocessed := safeSlice(items, startIndex, snapshotEndExclusive)
+	notifications := unprocessed
+	if len(notifications) > SyncFetchLimit {
+		notifications = notifications[:SyncFetchLimit]
+	}
+
+	endIndex := lastIndex
+	if len(notifications) > 0 {
+		endIndex = startIndex + len(notifications) - 1
+	}
+	hasMore := len(unprocessed) > len(notifications)
+	var nextStartIndex any
+	if hasMore {
+		nextStartIndex = endIndex + 1
+	}
+	return map[string]any{
+		"ok":               true,
+		"date":             date,
+		"startIndex":       startIndex,
+		"endIndex":         endIndex,
+		"nextStartIndex":   nextStartIndex,
+		"limit":            SyncFetchLimit,
+		"maxEndIndex":      maxEndIndex,
+		"returned":         len(notifications),
+		"totalUnprocessed": len(unprocessed),
+		"hasMore":          hasMore,
+		"notifications":    notifications,
+	}, nil
+}
+
+// CommitSync 推进指定日期的 checkpoint 到 endIndex（缺省按单批上限）。
+func CommitSync(dir, date, endIndexRaw string) (map[string]any, error) {
+	items := readDateFile(dir, date)
+	if len(items) == 0 {
+		return nil, errs.Newf(errs.CodeNotFound, "日期 %s 无通知数据", date)
+	}
+	checkpoint := readCheckpoint(dir)
+	lastIndex := lastIndexFor(checkpoint, date)
+
+	var committedIndex int
+	var commitMode string
+	if endIndexRaw != "" {
+		n, err := parseIndexOption(endIndexRaw, "--end-index")
+		if err != nil {
+			return nil, err
+		}
+		committedIndex = n
+		if committedIndex >= len(items) {
+			return nil, errs.New(errs.CodeInvalidArgument, "--end-index 超出当前日期通知文件范围")
+		}
+		if committedIndex < lastIndex {
+			return nil, errs.New(errs.CodeInvalidArgument, "--end-index 早于当前 checkpoint，不能回退消费进度")
+		}
+		if committedIndex > lastIndex+SyncFetchLimit {
+			return nil, errs.New(errs.CodeInvalidArgument, "--end-index 超出单批 fetch 上限，不能跳过未处理通知")
+		}
+		commitMode = "exact-end-index"
+	} else {
+		committedIndex = lastIndex + SyncFetchLimit
+		if committedIndex > len(items)-1 {
+			committedIndex = len(items) - 1
+		}
+		commitMode = "legacy-batch-limit"
+	}
+
+	hasMore := committedIndex < len(items)-1
+	checkpoint[date] = checkpointEntry{LastIndex: committedIndex}
+	if err := writeCheckpoint(dir, checkpoint); err != nil {
+		return nil, err
+	}
+	var nextStartIndex any
+	if hasMore {
+		nextStartIndex = committedIndex + 1
+	}
+	return map[string]any{
+		"ok":             true,
+		"date":           date,
+		"committedIndex": committedIndex,
+		"commitMode":     commitMode,
+		"limit":          SyncFetchLimit,
+		"hasMore":        hasMore,
+		"nextStartIndex": nextStartIndex,
+	}, nil
+}
+
+// safeSlice 返回 items[start:end]，对越界 / 反序做防御性夹取（对齐 JS slice 容错）。
+func safeSlice(items []StoredNotification, start, end int) []StoredNotification {
+	n := len(items)
+	if start < 0 {
+		start = 0
+	}
+	if start > n {
+		start = n
+	}
+	if end > n {
+		end = n
+	}
+	if end < start {
+		end = start
+	}
+	return items[start:end]
+}

From afe00a25d3df555a46dfad7b6ec76628e109a395 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 17:47:34 +0800
Subject: [PATCH 07/13] =?UTF-8?q?feat(go):=20Phase=202=20=E2=80=94=20light?=
 =?UTF-8?q?/lightrule=20=E7=A1=AC=E4=BB=B6=E6=8E=A7=E5=88=B6=E9=9D=A2?=
 =?UTF-8?q?=EF=BC=88=E5=8D=8F=E8=AE=AE=E7=BC=96=E7=A0=81=20+=20=E8=A7=84?=
 =?UTF-8?q?=E5=88=99=20CRUD=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

移植 src/vendor/light/* 与 light-rules/*：
- internal/light：repeat 归一、线协议逐字节编码（Unicode 档位 + 量化 + 色彩
  系数）、segments 校验（errors/warnings）、内置 presets（embed presets-v1.json）、
  发往灯效云 API 的 sender。协议用 presets 自带 base64 golden 逐字节验证（8/8）。
- internal/lightrule：meta.json 文件 CRUD（<profile>/light-rules/tasks/<name>），
  ALREADY_EXISTS / NOT_FOUND 语义 + 写路径串行化。
- daemon：新增 POST /light/send（segments/preset/rule 三选一）与
  /gateway/lightrules.{list,create,update,delete}（{ok,data} 外壳）。
- CLI：light send / +blink，lightrule list/show/create/update/delete/
  enable/disable/+on/+off，对齐 daemon-services.ts 代理形态。

端到端烟测通过：CRUD、校验报错、去重、light send 直达灯效云（空 key 优雅
拒绝）。gofmt/vet 全绿 + 5 平台交叉编译。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 internal/cli/cmd_light.go              | 347 +++++++++++++++++++++++
 internal/cli/root.go                   |   2 +
 internal/daemon/server.go              |   4 +
 internal/daemon/server_light.go        | 260 ++++++++++++++++++
 internal/light/env.go                  |  58 ++++
 internal/light/presets-v1.json         | 186 +++++++++++++
 internal/light/presets.go              |  48 ++++
 internal/light/protocol.go             | 300 ++++++++++++++++++++
 internal/light/protocol_golden_test.go |  25 ++
 internal/light/repeat.go               |  57 ++++
 internal/light/sender.go               | 137 ++++++++++
 internal/light/validators.go           | 363 +++++++++++++++++++++++++
 internal/lightrule/storage.go          | 290 ++++++++++++++++++++
 13 files changed, 2077 insertions(+)
 create mode 100644 internal/cli/cmd_light.go
 create mode 100644 internal/daemon/server_light.go
 create mode 100644 internal/light/env.go
 create mode 100644 internal/light/presets-v1.json
 create mode 100644 internal/light/presets.go
 create mode 100644 internal/light/protocol.go
 create mode 100644 internal/light/protocol_golden_test.go
 create mode 100644 internal/light/repeat.go
 create mode 100644 internal/light/sender.go
 create mode 100644 internal/light/validators.go
 create mode 100644 internal/lightrule/storage.go

diff --git a/internal/cli/cmd_light.go b/internal/cli/cmd_light.go
new file mode 100644
index 0000000..a5c7d27
--- /dev/null
+++ b/internal/cli/cmd_light.go
@@ -0,0 +1,347 @@
+package cli
+
+import (
+	"encoding/json"
+	"os"
+	"strconv"
+
+	"github.com/YoooClaw/cli/internal/clictx"
+	"github.com/YoooClaw/cli/internal/daemon"
+	"github.com/YoooClaw/cli/internal/errs"
+	"github.com/YoooClaw/cli/internal/prompt"
+	"github.com/spf13/cobra"
+)
+
+// ── light ──
+
+func newLightCmd() *cobra.Command {
+	c := &cobra.Command{Use: "light", Short: "灯效硬件控制 🟡"}
+
+	send := &cobra.Command{Use: "send", Short: "发送灯效指令到硬件（--segments / --preset / --rule 三选一）", Args: cobra.NoArgs, RunE: run(lightSend)}
+	send.Flags().String("segments", "", "灯效参数 JSON（原始段）")
+	send.Flags().String("preset", "", "内置预设 id（如 red-steady / red-strobe-3）")
+	send.Flags().String("rule", "", "已保存的 lightrule 名")
+	send.Flags().Bool("repeat", false, "无限循环播放（覆盖来源默认值）")
+	send.Flags().String("repeat-times", "", "整条组合重复次数（0=无限，覆盖来源默认值）")
+
+	blink := &cobra.Command{Use: "+blink", Short: "灯效连通性测试（red-strobe-3）", Args: cobra.NoArgs, RunE: run(lightBlink)}
+
+	c.AddCommand(send, blink)
+	return c
+}
+
+func lightSend(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	segments, preset, rule := flagStr(cmd, "segments"), flagStr(cmd, "preset"), flagStr(cmd, "rule")
+	if segments == "" && preset == "" && rule == "" {
+		return nil, errs.New(errs.CodeInvalidArgument, "需要 --segments / --preset / --rule 之一")
+	}
+	body := map[string]any{}
+	if segments != "" {
+		v, err := parseJSONArg(segments, "--segments")
+		if err != nil {
+			return nil, err
+		}
+		body["segments"] = v
+	}
+	if preset != "" {
+		body["preset"] = preset
+	}
+	if rule != "" {
+		body["rule"] = rule
+	}
+	if flagBool(cmd, "repeat") {
+		body["repeat"] = true
+	}
+	if rt := flagStr(cmd, "repeat-times"); rt != "" {
+		n, err := strconv.ParseFloat(rt, 64)
+		if err != nil {
+			return nil, errs.New(errs.CodeInvalidArgument, "--repeat-times 必须是数字")
+		}
+		body["repeat_times"] = n
+	}
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, resBody, err := c.Request("POST", "/light/send", body)
+	return resBody, err
+}
+
+func lightBlink(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, resBody, err := c.Request("POST", "/light/send", map[string]any{"preset": "red-strobe-3"})
+	return resBody, err
+}
+
+// ── lightrule ──
+
+func newLightruleCmd() *cobra.Command {
+	c := &cobra.Command{Use: "lightrule", Short: "灯效规则管理 🟡"}
+
+	list := &cobra.Command{Use: "list", Short: "列出所有规则及状态", Args: cobra.NoArgs, RunE: run(lightruleList)}
+	show := &cobra.Command{Use: "show <id>", Short: "查看单条规则详情", Args: cobra.ExactArgs(1), RunE: run(lightruleShow)}
+
+	create := &cobra.Command{Use: "create", Short: "创建规则（--from-file / --intent ...）", Args: cobra.NoArgs, RunE: run(lightruleCreate)}
+	addRuleFlags(create)
+	update := &cobra.Command{Use: "update <id>", Short: "更新现有规则", Args: cobra.ExactArgs(1), RunE: run(lightruleUpdate)}
+	addRuleFlags(update)
+
+	del := &cobra.Command{Use: "delete <id>", Short: "删除规则（--yes）", Args: cobra.ExactArgs(1), RunE: run(lightruleDelete)}
+	del.Flags().Bool("yes", false, "跳过确认")
+	enable := &cobra.Command{Use: "enable <id>", Short: "启用单条规则", Args: cobra.ExactArgs(1), RunE: run(lightruleEnable)}
+	disable := &cobra.Command{Use: "disable <id>", Short: "停用单条规则", Args: cobra.ExactArgs(1), RunE: run(lightruleDisable)}
+
+	on := &cobra.Command{Use: "+on", Short: "启用所有规则", Args: cobra.NoArgs, RunE: run(lightruleOn)}
+	off := &cobra.Command{Use: "+off", Short: "停用所有规则（保留定义）", Args: cobra.NoArgs, RunE: run(lightruleOff)}
+
+	c.AddCommand(list, show, create, update, del, enable, disable, on, off)
+	return c
+}
+
+func addRuleFlags(c *cobra.Command) {
+	c.Flags().String("from-file", "", "从 JSON 读规则（- 为 stdin）")
+	c.Flags().String("name", "", "规则名")
+	c.Flags().String("intent", "", "自然语言意图描述")
+	c.Flags().String("light-action", "", "命中后的 light 动作 JSON")
+	c.Flags().String("match-rules", "", "前置硬过滤规则 JSON")
+}
+
+func lightruleListRules(c *daemon.Client) ([]any, error) {
+	_, body, err := c.Request("POST", "/gateway/lightrules.list", map[string]any{})
+	if err != nil {
+		return nil, err
+	}
+	if m, ok := body.(map[string]any); ok {
+		if data, ok := m["data"].(map[string]any); ok {
+			if rules, ok := data["rules"].([]any); ok {
+				return rules, nil
+			}
+		}
+	}
+	return []any{}, nil
+}
+
+func lightruleList(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	rules, err := lightruleListRules(c)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{"ok": true, "rules": rules}, nil
+}
+
+func lightruleShow(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	rules, err := lightruleListRules(c)
+	if err != nil {
+		return nil, err
+	}
+	id := args[0]
+	for _, r := range rules {
+		if m, ok := r.(map[string]any); ok && (m["id"] == id || m["name"] == id) {
+			return map[string]any{"ok": true, "rule": m}, nil
+		}
+	}
+	return nil, errs.New(errs.CodeNotFound, "规则不存在："+id)
+}
+
+func buildRuleParams(cmd *cobra.Command, name string) (map[string]any, error) {
+	if ff := flagStr(cmd, "from-file"); ff != "" {
+		var raw string
+		if ff == "-" {
+			s, err := prompt.ReadStdin()
+			if err != nil {
+				return nil, err
+			}
+			raw = s
+		} else {
+			b, err := os.ReadFile(ff)
+			if err != nil {
+				return nil, errs.New(errs.CodeInvalidArgument, "无法读取文件："+ff)
+			}
+			raw = string(b)
+		}
+		var m map[string]any
+		if json.Unmarshal([]byte(raw), &m) != nil {
+			return nil, errs.New(errs.CodeInvalidArgument, "--from-file 内容不是合法 JSON 对象")
+		}
+		return m, nil
+	}
+
+	params := map[string]any{}
+	if name != "" {
+		params["name"] = name
+	}
+	if n := flagStr(cmd, "name"); n != "" {
+		params["name"] = n
+	}
+	if intent := flagStr(cmd, "intent"); intent != "" {
+		params["description"] = intent
+	}
+	if la := flagStr(cmd, "light-action"); la != "" {
+		action, err := parseJSONArg(la, "--light-action")
+		if err != nil {
+			return nil, err
+		}
+		params["segments"] = segmentsFromAction(action)
+	}
+	if mr := flagStr(cmd, "match-rules"); mr != "" {
+		match, err := parseJSONArg(mr, "--match-rules")
+		if err != nil {
+			return nil, err
+		}
+		params["matchRules"] = match
+	}
+	return params, nil
+}
+
+// segmentsFromAction 对齐 TS：数组直接用；对象取 .segments，缺省回退整体。
+func segmentsFromAction(action any) any {
+	if _, ok := action.([]any); ok {
+		return action
+	}
+	if obj, ok := action.(map[string]any); ok {
+		if segs, ok := obj["segments"]; ok {
+			return segs
+		}
+	}
+	return action
+}
+
+func lightruleCreate(ctx *clictx.Context, cmd *cobra.Command, _ []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	params, err := buildRuleParams(cmd, "")
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("POST", "/gateway/lightrules.create", params)
+	if err != nil {
+		return nil, err
+	}
+	if m, ok := body.(map[string]any); !ok || m["ok"] == false {
+		return nil, errs.New(errs.CodeInvalidArgument, createErrorMessage(body))
+	}
+	return dataOrBody(body), nil
+}
+
+func lightruleUpdate(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	params, err := buildRuleParams(cmd, args[0])
+	if err != nil {
+		return nil, err
+	}
+	params["name"] = args[0]
+	_, body, err := c.Request("POST", "/gateway/lightrules.update", params)
+	if err != nil {
+		return nil, err
+	}
+	return dataOrBody(body), nil
+}
+
+func lightruleDelete(ctx *clictx.Context, cmd *cobra.Command, args []string) (any, error) {
+	if !flagBool(cmd, "yes") {
+		ok, err := prompt.Confirm("确认删除规则 `"+args[0]+"`？", false)
+		if err != nil {
+			return nil, err
+		}
+		if !ok {
+			return nil, errs.New(errs.CodeConfirmationRequired, "已取消")
+		}
+	}
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("POST", "/gateway/lightrules.delete", map[string]any{"name": args[0]})
+	if err != nil {
+		return nil, err
+	}
+	return dataOrBody(body), nil
+}
+
+func lightruleEnable(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	return lightruleSetEnabled(ctx, args[0], true)
+}
+
+func lightruleDisable(ctx *clictx.Context, _ *cobra.Command, args []string) (any, error) {
+	return lightruleSetEnabled(ctx, args[0], false)
+}
+
+func lightruleSetEnabled(ctx *clictx.Context, id string, enabled bool) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	_, body, err := c.Request("POST", "/gateway/lightrules.update", map[string]any{"name": id, "enabled": enabled})
+	if err != nil {
+		return nil, err
+	}
+	return dataOrBody(body), nil
+}
+
+func lightruleOn(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return lightruleToggleAll(ctx, true)
+}
+
+func lightruleOff(ctx *clictx.Context, _ *cobra.Command, _ []string) (any, error) {
+	return lightruleToggleAll(ctx, false)
+}
+
+func lightruleToggleAll(ctx *clictx.Context, enabled bool) (any, error) {
+	c, err := daemonProxy(ctx)
+	if err != nil {
+		return nil, err
+	}
+	rules, err := lightruleListRules(c)
+	if err != nil {
+		return nil, err
+	}
+	results := make([]any, 0, len(rules))
+	for _, r := range rules {
+		m, _ := r.(map[string]any)
+		name := m["name"]
+		_, body, err := c.Request("POST", "/gateway/lightrules.update", map[string]any{"name": name, "enabled": enabled})
+		ok := err == nil
+		if bm, isMap := body.(map[string]any); isMap && bm["ok"] == false {
+			ok = false
+		}
+		results = append(results, map[string]any{"name": name, "ok": ok})
+	}
+	return map[string]any{"ok": true, "enabled": enabled, "count": len(results), "results": results}, nil
+}
+
+// dataOrBody 返回 gateway 响应里的 data；缺省回退整个 body。
+func dataOrBody(body any) any {
+	if m, ok := body.(map[string]any); ok {
+		if data, ok := m["data"]; ok {
+			return data
+		}
+	}
+	return body
+}
+
+func createErrorMessage(body any) string {
+	if m, ok := body.(map[string]any); ok {
+		if e, ok := m["error"]; ok {
+			data, _ := json.Marshal(e)
+			return string(data)
+		}
+	}
+	data, _ := json.Marshal(body)
+	return string(data)
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index aa4abcf..64200d1 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -36,6 +36,8 @@ func newRootCmd() *cobra.Command {
 		newRecordingCmd(),
 		newImageCmd(),
 		newMonitorCmd(),
+		newLightCmd(),
+		newLightruleCmd(),
 		newTunnelCmd(),
 		newGatewayCmd(),
 		newAPICmd(),
diff --git a/internal/daemon/server.go b/internal/daemon/server.go
index e5388f7..f6a37ba 100644
--- a/internal/daemon/server.go
+++ b/internal/daemon/server.go
@@ -175,6 +175,10 @@ func (s *server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		s.handleIngest(w, r, authCtx, "items")
 	case path == "/monitors" || strings.HasPrefix(path, "/monitors/"):
 		s.handleMonitors(w, r, path)
+	case path == "/light/send" && r.Method == http.MethodPost:
+		s.handleLightSend(w, r)
+	case strings.HasPrefix(path, "/gateway/lightrules."):
+		s.handleLightrules(w, r, path)
 	case strings.HasPrefix(path, "/tunnel/"):
 		s.handleTunnel(w, r, path)
 	default:
diff --git a/internal/daemon/server_light.go b/internal/daemon/server_light.go
new file mode 100644
index 0000000..1b6839e
--- /dev/null
+++ b/internal/daemon/server_light.go
@@ -0,0 +1,260 @@
+package daemon
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/light"
+	"github.com/YoooClaw/cli/internal/lightrule"
+)
+
+// handleLightSend 处理 POST /light/send：segments / preset / rule 三选一，编码后下发灯效云 API。
+func (s *server) handleLightSend(w http.ResponseWriter, r *http.Request) {
+	var body map[string]any
+	if !decodeBody(w, r, &body) {
+		return
+	}
+
+	repeatInput := light.RepeatInputFromAny(body["repeat"], body["repeat_times"])
+	reason, _ := body["reason"].(string)
+	title, _ := body["title"].(string)
+
+	var segments []map[string]any
+	switch {
+	case body["segments"] != nil:
+		res := light.ValidateSegments(body["segments"])
+		if !res.Valid {
+			writeJSON(w, 400, errBody("VALIDATION_FAILED", validationMessage(res)))
+			return
+		}
+		segments = res.Segments
+	case asString(body["preset"]) != "":
+		preset, ok := light.LookupPreset(asString(body["preset"]))
+		if !ok {
+			writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知预设："+asString(body["preset"])))
+			return
+		}
+		segments = preset.Segments
+		if body["repeat"] == nil && body["repeat_times"] == nil {
+			rt := float64(preset.RepeatTimes)
+			repeatInput = light.RepeatInput{RepeatTimes: &rt}
+		}
+	case asString(body["rule"]) != "":
+		rule := lightrule.Get(s.ctx.Paths.LightRules, asString(body["rule"]))
+		if rule == nil {
+			writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "灯效规则不存在："+asString(body["rule"])))
+			return
+		}
+		segments = rule.Segments
+		if body["repeat"] == nil && body["repeat_times"] == nil {
+			rt := float64(rule.RepeatTimes)
+			repeatInput = light.RepeatInput{RepeatTimes: &rt}
+		}
+	default:
+		writeJSON(w, 400, errBody("INVALID_PARAMS", "需要 segments / preset / rule 之一"))
+		return
+	}
+
+	apiKey := creds.ResolveAPIKey().Value
+	result := light.SendLightEffect(apiKey, segments, repeatInput, reason, title, s.logger)
+	writeJSON(w, 200, result)
+}
+
+// handleLightrules 处理 /gateway/lightrules.{list,create,update,delete}。
+func (s *server) handleLightrules(w http.ResponseWriter, r *http.Request, path string) {
+	if r.Method != http.MethodPost {
+		writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
+		return
+	}
+	method := strings.TrimPrefix(path, "/gateway/")
+	base := s.ctx.Paths.LightRules
+
+	switch method {
+	case "lightrules.list":
+		rules := []map[string]any{}
+		for _, m := range lightrule.List(base) {
+			rm := metaToMap(m)
+			rm["id"] = m.Name
+			rules = append(rules, rm)
+		}
+		gatewayOK(w, map[string]any{"ok": true, "rules": rules})
+
+	case "lightrules.create":
+		var body map[string]any
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		name := asString(body["name"])
+		if name == "" {
+			gatewayErr(w, "INVALID_PARAMS", "name is required")
+			return
+		}
+		description := asString(body["description"])
+		if description == "" {
+			gatewayErr(w, "INVALID_PARAMS", "description is required")
+			return
+		}
+		title := strings.TrimSpace(asString(body["title"]))
+		if title == "" {
+			title = name
+		}
+		res := light.ValidateSegments(body["segments"])
+		if !res.Valid {
+			gatewayErr(w, "VALIDATION_FAILED", validationErrorsJSON(res))
+			return
+		}
+		meta, err := lightrule.Create(base, lightrule.CreateParams{
+			Name: name, Title: title, Description: description, Segments: res.Segments,
+			Repeat: boolPtrFromAny(body["repeat"]), RepeatTimes: floatPtrFromAny(body["repeat_times"]),
+		})
+		if err != nil {
+			gatewayRuleErr(w, err)
+			return
+		}
+		s.logger.Info("Light rule created: " + name)
+		gatewayOK(w, map[string]any{"ok": true, "id": meta.Name, "name": meta.Name, "title": meta.Title, "rule": metaToMap(*meta)})
+
+	case "lightrules.update":
+		var body map[string]any
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		name := resolveRuleIdentifier(body)
+		if name == "" {
+			gatewayErr(w, "INVALID_PARAMS", "name is required (or provide id/ruleId/ruleName)")
+			return
+		}
+		params := lightrule.UpdateParams{
+			Name:        name,
+			Repeat:      boolPtrFromAny(body["repeat"]),
+			RepeatTimes: floatPtrFromAny(body["repeat_times"]),
+			Enabled:     boolPtrFromAny(body["enabled"]),
+		}
+		if raw, ok := body["title"]; ok {
+			t := strings.TrimSpace(asString(raw))
+			if t == "" {
+				gatewayErr(w, "INVALID_PARAMS", "title must be a non-empty string")
+				return
+			}
+			params.Title = &t
+		}
+		if raw, ok := body["description"]; ok {
+			d, isStr := raw.(string)
+			if !isStr {
+				gatewayErr(w, "INVALID_PARAMS", "description must be a string")
+				return
+			}
+			params.Description = &d
+		}
+		if body["segments"] != nil {
+			res := light.ValidateSegments(body["segments"])
+			if !res.Valid {
+				gatewayErr(w, "VALIDATION_FAILED", validationErrorsJSON(res))
+				return
+			}
+			params.Segments = res.Segments
+			params.HasSegments = true
+		}
+		meta, err := lightrule.Update(base, params)
+		if err != nil {
+			gatewayRuleErr(w, err)
+			return
+		}
+		s.logger.Info("Light rule updated: " + name)
+		gatewayOK(w, map[string]any{"ok": true, "id": meta.Name, "name": meta.Name, "title": meta.Title, "updated": true, "rule": metaToMap(*meta)})
+
+	case "lightrules.delete":
+		var body map[string]any
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		name := resolveRuleIdentifier(body)
+		if name == "" {
+			gatewayErr(w, "INVALID_PARAMS", "name is required (or provide id/ruleId/ruleName)")
+			return
+		}
+		deleted, err := lightrule.Delete(base, name)
+		if err != nil {
+			gatewayRuleErr(w, err)
+			return
+		}
+		s.logger.Info("Light rule deleted: " + deleted)
+		gatewayOK(w, map[string]any{"ok": true, "id": deleted, "name": deleted, "deleted": true})
+
+	default:
+		writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
+	}
+}
+
+// gatewayOK / gatewayErr 统一 gateway 响应外壳：CLI 读取 res.body.data。
+func gatewayOK(w http.ResponseWriter, payload any) {
+	writeJSON(w, 200, map[string]any{"ok": true, "data": payload})
+}
+
+func gatewayErr(w http.ResponseWriter, code, message string) {
+	writeJSON(w, 200, map[string]any{"ok": false, "error": map[string]any{"code": code, "message": message}})
+}
+
+func gatewayRuleErr(w http.ResponseWriter, err error) {
+	if e, ok := err.(*lightrule.Error); ok {
+		gatewayErr(w, e.Code, e.Message)
+		return
+	}
+	gatewayErr(w, "INTERNAL_ERROR", err.Error())
+}
+
+func resolveRuleIdentifier(body map[string]any) string {
+	for _, key := range []string{"name", "id", "ruleId", "ruleName"} {
+		if s := asString(body[key]); s != "" {
+			n := strings.TrimSpace(s)
+			if strings.HasSuffix(strings.ToLower(n), ".json") {
+				n = n[:len(n)-len(".json")]
+			}
+			if n != "" {
+				return n
+			}
+		}
+	}
+	return ""
+}
+
+func metaToMap(m lightrule.Meta) map[string]any {
+	data, _ := json.Marshal(m)
+	var out map[string]any
+	_ = json.Unmarshal(data, &out)
+	return out
+}
+
+func validationMessage(res light.ValidationResult) string {
+	parts := make([]string, len(res.Errors))
+	for i, e := range res.Errors {
+		parts[i] = e.Field + ": " + e.Message
+	}
+	return strings.Join(parts, "; ")
+}
+
+func validationErrorsJSON(res light.ValidationResult) string {
+	data, _ := json.Marshal(res.Errors)
+	return string(data)
+}
+
+func asString(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+func boolPtrFromAny(v any) *bool {
+	if b, ok := v.(bool); ok {
+		return &b
+	}
+	return nil
+}
+
+func floatPtrFromAny(v any) *float64 {
+	if f, ok := v.(float64); ok {
+		return &f
+	}
+	return nil
+}
diff --git a/internal/light/env.go b/internal/light/env.go
new file mode 100644
index 0000000..f8f4956
--- /dev/null
+++ b/internal/light/env.go
@@ -0,0 +1,58 @@
+package light
+
+import (
+	"os"
+	"regexp"
+	"strings"
+)
+
+// 默认环境主机（构建期可通过 OPENCLAW_HOST_* 注入覆盖）。
+var defaultEnvHosts = map[string]string{
+	"development": "openclaw-service-dev.yoooclaw.com",
+	"test":        "openclaw-service-test.yoooclaw.com",
+	"production":  "openclaw-service.yoooclaw.com",
+}
+
+var schemeRE = regexp.MustCompile(`^(https?|wss?)://`)
+var trailingSlashRE = regexp.MustCompile(`/+$`)
+
+func normalizeHost(host string) string {
+	trimmed := strings.TrimSpace(host)
+	if trimmed == "" {
+		return ""
+	}
+	trimmed = schemeRE.ReplaceAllString(trimmed, "")
+	return trailingSlashRE.ReplaceAllString(trimmed, "")
+}
+
+// loadEnvName 解析当前环境名（PHONE_NOTIFICATIONS_ENV 环境变量优先，否则 production）。
+func loadEnvName() string {
+	env := strings.TrimSpace(os.Getenv("PHONE_NOTIFICATIONS_ENV"))
+	switch env {
+	case "development", "test", "production":
+		return env
+	}
+	return "production"
+}
+
+func envHost() string {
+	env := loadEnvName()
+	var override string
+	switch env {
+	case "development":
+		override = os.Getenv("OPENCLAW_HOST_DEVELOPMENT")
+	case "test":
+		override = os.Getenv("OPENCLAW_HOST_TEST")
+	case "production":
+		override = os.Getenv("OPENCLAW_HOST_PRODUCTION")
+	}
+	if h := normalizeHost(override); h != "" {
+		return h
+	}
+	return defaultEnvHosts[env]
+}
+
+// LightAPIURL 返回灯效云 API 端点。
+func LightAPIURL() string {
+	return "https://" + envHost() + "/api/message/tob/sendMessage"
+}
diff --git a/internal/light/presets-v1.json b/internal/light/presets-v1.json
new file mode 100644
index 0000000..e883c40
--- /dev/null
+++ b/internal/light/presets-v1.json
@@ -0,0 +1,186 @@
+{
+  "version": "v1",
+  "presets": [
+    {
+      "presetId": "red-steady",
+      "displayName": "红色常亮",
+      "description": "红灯持续亮起 5 秒",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "steady",
+          "duration_s": 5,
+          "brightness": 192,
+          "color": {
+            "r": 255,
+            "g": 0,
+            "b": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBzdGVhZHkgKDEgc2VnbWVudCnCmsKDwoTChMKRwoDCgA=="
+    },
+    {
+      "presetId": "red-breath",
+      "displayName": "红色呼吸",
+      "description": "红色缓慢呼吸约两轮",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "breath",
+          "duration_s": 8,
+          "brightness": 192,
+          "color": {
+            "r": 255,
+            "g": 0,
+            "b": 0
+          },
+          "breath_timing": {
+            "rise_ms": 2080,
+            "hold_ms": 0,
+            "fall_ms": 2080,
+            "off_ms": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBicmVhdGggKDEgc2VnbWVudCnCmsKBwpLCgsKRwoLCkcKEwpHCgMKA"
+    },
+    {
+      "presetId": "red-strobe-3",
+      "displayName": "红色三闪",
+      "description": "红色短促频闪，体感接近三闪",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "strobe",
+          "duration_s": 1,
+          "interval_ms": 300,
+          "brightness": 192,
+          "color": {
+            "r": 255,
+            "g": 0,
+            "b": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBzdHJvYmUgKDEgc2VnbWVudCnCmsKCwoHCg8KEwpHCgMKA"
+    },
+    {
+      "presetId": "green-steady",
+      "displayName": "绿色常亮",
+      "description": "绿灯持续亮起 5 秒",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "steady",
+          "duration_s": 5,
+          "brightness": 192,
+          "color": {
+            "r": 0,
+            "g": 255,
+            "b": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBzdGVhZHkgKDEgc2VnbWVudCnCmsKDwoTChMKAwpHCgA=="
+    },
+    {
+      "presetId": "green-breath",
+      "displayName": "绿色呼吸",
+      "description": "绿色缓慢呼吸约两轮",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "breath",
+          "duration_s": 8,
+          "brightness": 192,
+          "color": {
+            "r": 0,
+            "g": 255,
+            "b": 0
+          },
+          "breath_timing": {
+            "rise_ms": 2080,
+            "hold_ms": 0,
+            "fall_ms": 2080,
+            "off_ms": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBicmVhdGggKDEgc2VnbWVudCnCmsKBwpLCgsKRwoLCkcKEwoDCkcKA"
+    },
+    {
+      "presetId": "blue-wave",
+      "displayName": "蓝色波浪",
+      "description": "蓝色从左到右流动一轮",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "wave",
+          "duration_s": 5,
+          "interval_ms": 200,
+          "brightness": 192,
+          "color": {
+            "r": 0,
+            "g": 0,
+            "b": 255
+          },
+          "direction": "ltr",
+          "window": 2,
+          "background": {
+            "r": 0,
+            "g": 0,
+            "b": 0,
+            "brightness": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiB3YXZlICgxIHNlZ21lbnQpwprCgMKEwoLChMKAwoDCkcKAwoHCgMKAwoDCgA=="
+    },
+    {
+      "presetId": "blue-breath",
+      "displayName": "蓝色呼吸",
+      "description": "蓝色缓慢呼吸约两轮",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "breath",
+          "duration_s": 8,
+          "brightness": 192,
+          "color": {
+            "r": 0,
+            "g": 0,
+            "b": 255
+          },
+          "breath_timing": {
+            "rise_ms": 2080,
+            "hold_ms": 0,
+            "fall_ms": 2080,
+            "off_ms": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBicmVhdGggKDEgc2VnbWVudCnCmsKBwpLCgsKRwoLCkcKEwoDCgMKR"
+    },
+    {
+      "presetId": "yellow-strobe-3",
+      "displayName": "黄色三闪",
+      "description": "黄色短促频闪，体感接近三闪",
+      "repeat_times": 1,
+      "segments": [
+        {
+          "mode": "strobe",
+          "duration_s": 1,
+          "interval_ms": 300,
+          "brightness": 192,
+          "color": {
+            "r": 255,
+            "g": 255,
+            "b": 0
+          }
+        }
+      ],
+      "base64": "RWZmZWN0OiBzdHJvYmUgKDEgc2VnbWVudCnCmsKCwoHCg8KEwpHCgsKA"
+    }
+  ]
+}
diff --git a/internal/light/presets.go b/internal/light/presets.go
new file mode 100644
index 0000000..5b8efdf
--- /dev/null
+++ b/internal/light/presets.go
@@ -0,0 +1,48 @@
+package light
+
+import (
+	_ "embed"
+	"encoding/json"
+)
+
+//go:embed presets-v1.json
+var presetsData []byte
+
+// Preset 是内置灯效预设（presets-v1.json 的元素）。
+type Preset struct {
+	PresetID    string           `json:"presetId"`
+	DisplayName string           `json:"displayName"`
+	Description string           `json:"description"`
+	RepeatTimes int              `json:"repeat_times"`
+	Segments    []map[string]any `json:"segments"`
+	Base64      string           `json:"base64"`
+}
+
+type presetsFile struct {
+	Version string   `json:"version"`
+	Presets []Preset `json:"presets"`
+}
+
+var loadedPresets []Preset
+
+func init() {
+	var f presetsFile
+	if err := json.Unmarshal(presetsData, &f); err == nil {
+		loadedPresets = f.Presets
+	}
+}
+
+// Presets 返回全部内置预设。
+func Presets() []Preset {
+	return loadedPresets
+}
+
+// LookupPreset 按 presetId 查找内置预设。
+func LookupPreset(id string) (Preset, bool) {
+	for _, p := range loadedPresets {
+		if p.PresetID == id {
+			return p, true
+		}
+	}
+	return Preset{}, false
+}
diff --git a/internal/light/protocol.go b/internal/light/protocol.go
new file mode 100644
index 0000000..c8c6bb7
--- /dev/null
+++ b/internal/light/protocol.go
@@ -0,0 +1,300 @@
+package light
+
+import (
+	"fmt"
+	"math"
+	"strings"
+)
+
+// MaxLightSegments 是单次灯效组合的最大段数。
+const MaxLightSegments = 12
+
+// protocolDigits 把量化档位 v0–v11 映射到线协议字符（与固件约定一致）。
+var protocolDigits = []rune{
+	0x80, 0x81, 0x82, 0x83, 0x84, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97,
+}
+
+// š = 播放一轮；› = 无限循环。
+const (
+	ledSeparatorOnce = "š"
+	ledSeparatorLoop = "›"
+)
+
+// 量化档位表（v0–v10 按下标映射；个别字段对 0 / 缺省做特判）。
+var (
+	durationStepsS            = []float64{0.5, 1, 2, 3, 5, 6, 8, 16, 24, 32, 48}
+	intervalStepsMs           = []float64{50, 100, 200, 300, 500, 600, 800, 1600, 2400, 3200, 4800}
+	breathStepsMs             = []float64{1040, 1560, 2080, 2600, 3100, 4160}
+	brightnessSteps           = []float64{32, 64, 96, 128, 192, 255}
+	colorSteps                = []float64{0, 32, 64, 128, 192, 255}
+	backgroundBrightnessSteps = []float64{0, 32, 64, 96, 128, 192, 255}
+)
+
+var (
+	multiChannelColorCoefficients = rgb{1, 0.25, 0.25}
+	pureWhiteColorCoefficients    = rgb{1, 0.35, 0.35}
+)
+
+type rgb struct{ r, g, b float64 }
+
+// modeToIndex 把 mode 映射到线协议的 M 值。color_flow 编码到 M=v4。
+var modeToIndex = map[string]int{
+	"wave": 0, "breath": 1, "strobe": 2, "steady": 3, "color_flow": 4, "pixel_frame": 5,
+}
+
+// BuildLightEffectApnsBody 把 segments 编码成 APNs 可见文本 + 分隔符 + 线协议负载。
+func BuildLightEffectApnsBody(segments []map[string]any, repeatInput RepeatInput, visibleTextOverride string) (string, error) {
+	if len(segments) < 1 || len(segments) > MaxLightSegments {
+		return "", fmt.Errorf("light_control supports 1-%d segments", MaxLightSegments)
+	}
+	if err := assertSegmentsValid(segments); err != nil {
+		return "", err
+	}
+	repeatTimes, err := NormalizeRepeatTimes(repeatInput)
+	if err != nil {
+		return "", err
+	}
+	if err := AssertAncsRepeatTimes(repeatTimes); err != nil {
+		return "", err
+	}
+
+	visibleText := resolveVisibleText(visibleTextOverride, segments)
+	separator := ledSeparatorOnce
+	if repeatTimes == 0 {
+		separator = ledSeparatorLoop
+	}
+	var payload strings.Builder
+	for _, seg := range segments {
+		payload.WriteString(encodeSegment(seg))
+	}
+	return visibleText + separator + payload.String(), nil
+}
+
+func resolveVisibleText(override string, segments []map[string]any) string {
+	if trimmed := strings.TrimSpace(override); trimmed != "" {
+		return trimmed
+	}
+	return summarizeSegments(segments)
+}
+
+func summarizeSegments(segments []map[string]any) string {
+	modes := make([]string, len(segments))
+	for i, seg := range segments {
+		modes[i], _ = seg["mode"].(string)
+	}
+	plural := ""
+	if len(segments) > 1 {
+		plural = "s"
+	}
+	return fmt.Sprintf("Effect: %s (%d segment%s)", strings.Join(modes, "+"), len(segments), plural)
+}
+
+func assertSegmentsValid(segments []map[string]any) error {
+	anySegs := make([]any, len(segments))
+	for i, s := range segments {
+		anySegs[i] = s
+	}
+	res := ValidateSegments(anySegs)
+	if res.Valid {
+		return nil
+	}
+	parts := make([]string, len(res.Errors))
+	for i, e := range res.Errors {
+		parts[i] = e.Field + ": " + e.Message
+	}
+	return fmt.Errorf("%s", strings.Join(parts, "; "))
+}
+
+func encodeSegment(seg map[string]any) string {
+	mode, _ := seg["mode"].(string)
+	values := []int{modeToIndex[mode], quantizeDuration(numOr(seg, "duration_s", 0))}
+
+	switch mode {
+	case "wave", "color_flow":
+		color := normalizeProtocolColor(mapField(seg, "color"))
+		background := normalizeProtocolColor(mapField(seg, "background"))
+		values = append(values,
+			quantize(numOr(seg, "interval_ms", 200), intervalStepsMs),
+			quantizeBrightnessValue(numOr(seg, "brightness", 0)),
+			quantize(color.r, colorSteps), quantize(color.g, colorSteps), quantize(color.b, colorSteps),
+			directionValue(seg),
+			quantizeWindow(numOr(seg, "window", 2)),
+			quantize(background.r, colorSteps), quantize(background.g, colorSteps), quantize(background.b, colorSteps),
+			quantize(bgBrightness(seg), backgroundBrightnessSteps),
+		)
+	case "breath":
+		color := normalizeProtocolColor(mapField(seg, "color"))
+		bt := mapField(seg, "breath_timing")
+		rise, riseOK := numField(bt, "rise_ms")
+		hold, holdOK := numField(bt, "hold_ms")
+		fall, fallOK := numField(bt, "fall_ms")
+		off, offOK := numField(bt, "off_ms")
+		values = append(values,
+			quantizeBreathRiseFall(rise, riseOK),
+			quantizeBreathHoldOff(hold, holdOK),
+			quantizeBreathRiseFall(fall, fallOK),
+			quantizeBreathHoldOff(off, offOK),
+			quantizeBrightnessValue(numOr(seg, "brightness", 0)),
+			quantize(color.r, colorSteps), quantize(color.g, colorSteps), quantize(color.b, colorSteps),
+		)
+	case "strobe":
+		color := normalizeProtocolColor(mapField(seg, "color"))
+		values = append(values,
+			quantize(numOr(seg, "interval_ms", 200), intervalStepsMs),
+			quantizeBrightnessValue(numOr(seg, "brightness", 0)),
+			quantize(color.r, colorSteps), quantize(color.g, colorSteps), quantize(color.b, colorSteps),
+		)
+	case "steady":
+		color := normalizeProtocolColor(mapField(seg, "color"))
+		values = append(values,
+			quantizeBrightnessValue(numOr(seg, "brightness", 0)),
+			quantize(color.r, colorSteps), quantize(color.g, colorSteps), quantize(color.b, colorSteps),
+		)
+	case "pixel_frame":
+		values = encodePixelFrameValues(values, seg)
+	}
+
+	var b strings.Builder
+	for _, v := range values {
+		b.WriteRune(protocolDigits[v])
+	}
+	return b.String()
+}
+
+func encodePixelFrameValues(common []int, seg map[string]any) []int {
+	pixels := sliceField(seg, "pixels")
+	values := append(common, len(pixels)-1)
+	for _, p := range pixels {
+		pm, _ := p.(map[string]any)
+		color := normalizeProtocolColor(mapField(pm, "color"))
+		idx, _ := numField(pm, "index")
+		br, _ := numField(pm, "brightness")
+		values = append(values,
+			int(idx),
+			quantize(color.r, colorSteps), quantize(color.g, colorSteps), quantize(color.b, colorSteps),
+			quantizeBrightnessValue(br),
+		)
+	}
+	return values
+}
+
+func directionValue(seg map[string]any) int {
+	if d, ok := seg["direction"].(string); ok && d == "rtl" {
+		return 1
+	}
+	return 0
+}
+
+func bgBrightness(seg map[string]any) float64 {
+	v, _ := numField(mapField(seg, "background"), "brightness")
+	return v
+}
+
+// normalizeProtocolColor 按通道数 / 纯白做色彩系数缩放（缺省通道按 0）。
+func normalizeProtocolColor(color map[string]any) rgb {
+	n := rgb{numOr(color, "r", 0), numOr(color, "g", 0), numOr(color, "b", 0)}
+	if n.r == 255 && n.g == 255 && n.b == 255 {
+		return applyColorCoefficients(n, pureWhiteColorCoefficients)
+	}
+	active := 0
+	for _, c := range []float64{n.r, n.g, n.b} {
+		if c > 0 {
+			active++
+		}
+	}
+	if active <= 1 {
+		return n
+	}
+	return applyColorCoefficients(n, multiChannelColorCoefficients)
+}
+
+func applyColorCoefficients(c, k rgb) rgb {
+	return rgb{scaleColorChannel(c.r, k.r), scaleColorChannel(c.g, k.g), scaleColorChannel(c.b, k.b)}
+}
+
+func scaleColorChannel(value, coefficient float64) float64 {
+	return math.Max(0, math.Min(255, math.Round(value*coefficient)))
+}
+
+func quantize(value float64, steps []float64) int {
+	bestIndex := 0
+	bestDistance := math.Inf(1)
+	for i, step := range steps {
+		if d := math.Abs(value - step); d < bestDistance {
+			bestIndex = i
+			bestDistance = d
+		}
+	}
+	return bestIndex
+}
+
+func quantizeDuration(durationS float64) int {
+	if durationS == 0 {
+		return 11
+	}
+	return quantize(durationS, durationStepsS)
+}
+
+func quantizeBrightnessValue(brightness float64) int {
+	if brightness == 0 {
+		return 11
+	}
+	return quantize(brightness, brightnessSteps)
+}
+
+func quantizeBreathRiseFall(value float64, present bool) int {
+	if !present {
+		value = 1040
+	}
+	return quantize(value, breathStepsMs)
+}
+
+func quantizeBreathHoldOff(value float64, present bool) int {
+	if present && value == 0 {
+		return 5
+	}
+	if !present {
+		value = 1040
+	}
+	return quantize(value, breathStepsMs[:5])
+}
+
+func quantizeWindow(value float64) int {
+	return int(value) - 1
+}
+
+// ── map/JSON 读取小工具 ──
+
+func numOr(m map[string]any, key string, def float64) float64 {
+	if v, ok := m[key].(float64); ok {
+		return v
+	}
+	return def
+}
+
+func numField(m map[string]any, key string) (float64, bool) {
+	if m == nil {
+		return 0, false
+	}
+	if v, ok := m[key].(float64); ok {
+		return v, true
+	}
+	return 0, false
+}
+
+func mapField(m map[string]any, key string) map[string]any {
+	if m == nil {
+		return nil
+	}
+	if v, ok := m[key].(map[string]any); ok {
+		return v
+	}
+	return nil
+}
+
+func sliceField(m map[string]any, key string) []any {
+	if v, ok := m[key].([]any); ok {
+		return v
+	}
+	return nil
+}
diff --git a/internal/light/protocol_golden_test.go b/internal/light/protocol_golden_test.go
new file mode 100644
index 0000000..d45633e
--- /dev/null
+++ b/internal/light/protocol_golden_test.go
@@ -0,0 +1,25 @@
+package light
+
+import (
+	"encoding/base64"
+	"testing"
+)
+
+// TestPresetGolden 用 presets-v1.json 自带的 base64 逐字节校验协议编码（body 的 UTF-8）。
+func TestPresetGolden(t *testing.T) {
+	if len(Presets()) == 0 {
+		t.Fatal("no presets loaded")
+	}
+	for _, p := range Presets() {
+		body, err := BuildLightEffectApnsBody(p.Segments, RepeatInput{RepeatTimes: f64(float64(p.RepeatTimes))}, "")
+		if err != nil {
+			t.Fatalf("%s: build error: %v", p.PresetID, err)
+		}
+		got := base64.StdEncoding.EncodeToString([]byte(body))
+		if got != p.Base64 {
+			t.Errorf("%s: golden mismatch\n want %s\n  got %s", p.PresetID, p.Base64, got)
+		}
+	}
+}
+
+func f64(v float64) *float64 { return &v }
diff --git a/internal/light/repeat.go b/internal/light/repeat.go
new file mode 100644
index 0000000..559a668
--- /dev/null
+++ b/internal/light/repeat.go
@@ -0,0 +1,57 @@
+// Package light 移植 phone-notifications 灯效硬件控制面：repeat 归一、线协议编码、
+// segments 校验、内置 presets 与发往灯效云 API 的 sender（对齐 src/vendor/light/*）。
+package light
+
+import (
+	"errors"
+	"math"
+)
+
+// RepeatInput 对齐 TS RepeatArgument 的「对象」形态：repeat（布尔）/ repeat_times（数字），
+// 二者皆可缺省（nil）。
+type RepeatInput struct {
+	Repeat      *bool
+	RepeatTimes *float64
+}
+
+// RepeatInputFromAny 从解码后的 JSON 值构造 RepeatInput（非布尔/数字按缺省处理）。
+func RepeatInputFromAny(repeat, repeatTimes any) RepeatInput {
+	var in RepeatInput
+	if b, ok := repeat.(bool); ok {
+		in.Repeat = &b
+	}
+	if n, ok := repeatTimes.(float64); ok {
+		in.RepeatTimes = &n
+	}
+	return in
+}
+
+// NormalizeRepeatTimes 把 RepeatInput 归一成 ANCS 语义的 repeat_times：
+// repeat_times 优先；其次 repeat（true=0 无限循环 / false=1 一轮）；都缺省则 1。
+func NormalizeRepeatTimes(in RepeatInput) (int, error) {
+	if in.RepeatTimes != nil {
+		return validateRepeatTimes(*in.RepeatTimes)
+	}
+	if in.Repeat != nil {
+		if *in.Repeat {
+			return 0, nil
+		}
+		return 1, nil
+	}
+	return 1, nil
+}
+
+func validateRepeatTimes(value float64) (int, error) {
+	if value != math.Trunc(value) || math.IsInf(value, 0) || math.IsNaN(value) || value < 0 {
+		return 0, errors.New("repeat_times 必须是 >=0 的整数")
+	}
+	return int(value), nil
+}
+
+// AssertAncsRepeatTimes 限定当前 ANCS 路径仅支持 0（无限循环）或 1（播放一轮）。
+func AssertAncsRepeatTimes(repeatTimes int) error {
+	if repeatTimes != 0 && repeatTimes != 1 {
+		return errors.New("当前 ANCS 路径仅支持 repeat_times=0（无限循环）或 1（播放一轮）；N>=2 需非 ANCS 路径")
+	}
+	return nil
+}
diff --git a/internal/light/sender.go b/internal/light/sender.go
new file mode 100644
index 0000000..ab52666
--- /dev/null
+++ b/internal/light/sender.go
@@ -0,0 +1,137 @@
+package light
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// 后端要求 appKey / templateId 写死在代码里（不再从 env 注入）。
+const (
+	lightAppKey     = "phone-notifications"
+	lightTemplateID = "1990771146010017800"
+)
+
+// Logger 是 sender 依赖的最小日志接口。
+type Logger interface {
+	Info(string)
+	Warn(string)
+}
+
+// SendResult 是一次灯效下发的结果。
+type SendResult struct {
+	OK          bool   `json:"ok"`
+	BizUniqueID string `json:"bizUniqueId,omitempty"`
+	Response    any    `json:"response,omitempty"`
+	Status      int    `json:"status,omitempty"`
+	Error       string `json:"error,omitempty"`
+}
+
+// SendLightEffect 把 segments 编码成线协议负载并 POST 到灯效云 API。
+func SendLightEffect(apiKey string, segments []map[string]any, repeatInput RepeatInput, reason, title string, logger Logger) SendResult {
+	apiURL := LightAPIURL()
+	resolvedTitle := resolveLightTitle(title, reason, segments)
+
+	if logger != nil {
+		logger.Info(fmt.Sprintf("Light sender: apiUrl=%s, appKey=%s…, templateId=%s, apiKey=%s, title=%s, reason=%s",
+			apiURL, truncate(lightAppKey, 8), lightTemplateID, maskKey(apiKey), resolvedTitle, reason))
+	}
+	if apiURL == "" {
+		return SendResult{OK: false, Error: "灯效 API 未配置，请确认构建时已封装 OPENCLAW_HOST_*"}
+	}
+
+	bizContent, err := BuildLightEffectApnsBody(segments, repeatInput, reason)
+	if err != nil {
+		return SendResult{OK: false, Error: err.Error()}
+	}
+	bizUniqueID := newUUID()
+
+	requestBody := map[string]any{
+		"appKey":      lightAppKey,
+		"bizMap":      map[string]any{"noticeType": "APP_NOTIFICATION_IMPORTANT", "title": resolvedTitle, "reason": reason},
+		"bizUniqueId": bizUniqueID,
+		"paramsMap":   map[string]any{"bizContent": bizContent},
+		"pushType":    "SPECIFY_PUSH",
+		"templateId":  lightTemplateID,
+	}
+	payload, _ := json.Marshal(requestBody)
+	if logger != nil {
+		logger.Info(fmt.Sprintf("Light sender: POST %s, bizUniqueId=%s, body=%s", apiURL, bizUniqueID, truncate(string(payload), 500)))
+	}
+
+	req, err := http.NewRequest(http.MethodPost, apiURL, bytes.NewReader(payload))
+	if err != nil {
+		return SendResult{OK: false, Error: err.Error()}
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Api-Key-Id", strings.TrimPrefix(apiKey, "Bearer "))
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	res, err := client.Do(req)
+	if err != nil {
+		return SendResult{OK: false, Error: err.Error()}
+	}
+	defer res.Body.Close()
+	resBody, _ := io.ReadAll(res.Body)
+
+	if res.StatusCode < 200 || res.StatusCode >= 300 {
+		if logger != nil {
+			logger.Warn(fmt.Sprintf("Light sender: FAILED %d, url=%s, resBody=%s", res.StatusCode, apiURL, truncate(string(resBody), 500)))
+		}
+		return SendResult{OK: false, Status: res.StatusCode, Error: string(resBody)}
+	}
+	if logger != nil {
+		logger.Info(fmt.Sprintf("Light sender: OK bizUniqueId=%s, resBody=%s", bizUniqueID, truncate(string(resBody), 200)))
+	}
+	var parsed any
+	if json.Unmarshal(resBody, &parsed) != nil {
+		parsed = string(resBody)
+	}
+	return SendResult{OK: true, BizUniqueID: bizUniqueID, Response: parsed}
+}
+
+func resolveLightTitle(title, reason string, segments []map[string]any) string {
+	if t := strings.TrimSpace(title); t != "" {
+		return t
+	}
+	if r := strings.TrimSpace(reason); r != "" {
+		return r
+	}
+	modes := make([]string, len(segments))
+	for i, seg := range segments {
+		modes[i], _ = seg["mode"].(string)
+	}
+	desc := strings.Join(modes, "+")
+	if desc == "" {
+		desc = "custom"
+	}
+	return "Effect: " + desc
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}
+
+func maskKey(apiKey string) string {
+	if apiKey == "" {
+		return "EMPTY"
+	}
+	return truncate(apiKey, 20)
+}
+
+// newUUID 生成 RFC 4122 v4 UUID。
+func newUUID() string {
+	var b [16]byte
+	_, _ = rand.Read(b[:])
+	b[6] = (b[6] & 0x0f) | 0x40
+	b[8] = (b[8] & 0x3f) | 0x80
+	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
+}
diff --git a/internal/light/validators.go b/internal/light/validators.go
new file mode 100644
index 0000000..dd6c13a
--- /dev/null
+++ b/internal/light/validators.go
@@ -0,0 +1,363 @@
+package light
+
+import (
+	"fmt"
+	"math"
+)
+
+// MaxSegments 是 segments 校验的上限（与 MaxLightSegments 同值）。
+const MaxSegments = 12
+
+// validModes 是允许的 segment 模式。
+var validModes = []string{"wave", "breath", "strobe", "steady", "color_flow", "pixel_frame"}
+
+// ValidationError 是单个字段的校验错误。
+type ValidationError struct {
+	Field   string `json:"field"`
+	Message string `json:"message"`
+}
+
+// ValidationWarning 是不阻塞的告警（如 color_flow 单锚点误用）。
+type ValidationWarning struct {
+	Field   string `json:"field"`
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+
+// ValidationResult 是 segments 校验结果。无效时 Errors 非空。
+type ValidationResult struct {
+	Valid    bool
+	Segments []map[string]any
+	Errors   []ValidationError
+	Warnings []ValidationWarning
+}
+
+// ValidateSegments 校验 segments（接受解码后的 JSON 值）。
+func ValidateSegments(raw any) ValidationResult {
+	arr, ok := raw.([]any)
+	if !ok {
+		return invalid("segments", "必须是数组")
+	}
+	if len(arr) == 0 {
+		return invalid("segments", "不能为空")
+	}
+	if len(arr) > MaxSegments {
+		return invalid("segments", fmt.Sprintf("最多 %d 段", MaxSegments))
+	}
+
+	var errs []ValidationError
+	var warnings []ValidationWarning
+	for i, seg := range arr {
+		validateSegment(seg, fmt.Sprintf("segments[%d]", i), &errs, &warnings)
+	}
+	if len(errs) > 0 {
+		return ValidationResult{Valid: false, Errors: errs}
+	}
+	segs := make([]map[string]any, len(arr))
+	for i, seg := range arr {
+		segs[i], _ = seg.(map[string]any)
+	}
+	return ValidationResult{Valid: true, Segments: segs, Warnings: warnings}
+}
+
+func invalid(field, message string) ValidationResult {
+	return ValidationResult{Valid: false, Errors: []ValidationError{{Field: field, Message: message}}}
+}
+
+func validateSegment(raw any, prefix string, errs *[]ValidationError, warnings *[]ValidationWarning) {
+	seg, ok := raw.(map[string]any)
+	if !ok {
+		add(errs, prefix, "必须是对象")
+		return
+	}
+
+	mode, _ := seg["mode"].(string)
+	if !contains(validModes, mode) {
+		add(errs, prefix+".mode", fmt.Sprintf("不支持的模式 '%v'，可选：%s", stringifyMode(seg["mode"]), joinSlash(validModes)))
+	}
+
+	validateNonNegativeNumber(seg["duration_s"], prefix+".duration_s", errs, "必须是 ≥0 的数字（0 表示无限时长）")
+
+	switch mode {
+	case "wave":
+		validateForegroundSegment(seg, prefix, errs)
+		validateOptionalNonNegativeNumber(seg["interval_ms"], prefix+".interval_ms", errs)
+		validateOptionalDirection(seg["direction"], prefix+".direction", errs)
+		validateOptionalWindow(seg["window"], prefix+".window", errs)
+		validateOptionalBackground(seg["background"], prefix+".background", errs)
+	case "color_flow":
+		validateForegroundSegment(seg, prefix, errs)
+		validateOptionalNonNegativeNumber(seg["interval_ms"], prefix+".interval_ms", errs)
+		validateOptionalDirection(seg["direction"], prefix+".direction", errs)
+		validateOptionalWindow(seg["window"], prefix+".window", errs)
+		validateOptionalBackground(seg["background"], prefix+".background", errs)
+		if !hasNonZeroRgb(seg["color"]) && !hasNonZeroRgb(seg["background"]) {
+			add(errs, prefix, "color_flow 至少需要一组非零颜色锚点（color 或 background）")
+		}
+		detectColorFlowSingleAnchorMisuse(seg, prefix, warnings)
+	case "breath":
+		validateForegroundSegment(seg, prefix, errs)
+		validateOptionalBreathTiming(seg["breath_timing"], prefix+".breath_timing", errs)
+	case "strobe":
+		validateForegroundSegment(seg, prefix, errs)
+		validateOptionalNonNegativeNumber(seg["interval_ms"], prefix+".interval_ms", errs)
+	case "steady":
+		validateForegroundSegment(seg, prefix, errs)
+	case "pixel_frame":
+		validatePixelFrame(seg["pixels"], prefix+".pixels", errs)
+	default:
+		validateOptionalNonNegativeNumber(seg["brightness"], prefix+".brightness", errs)
+		validateOptionalColor(seg["color"], prefix+".color", errs)
+		validateOptionalNonNegativeNumber(seg["interval_ms"], prefix+".interval_ms", errs)
+		validateOptionalDirection(seg["direction"], prefix+".direction", errs)
+		validateOptionalWindow(seg["window"], prefix+".window", errs)
+		validateOptionalBreathTiming(seg["breath_timing"], prefix+".breath_timing", errs)
+		validateOptionalBackground(seg["background"], prefix+".background", errs)
+	}
+}
+
+func validateForegroundSegment(seg map[string]any, prefix string, errs *[]ValidationError) {
+	validateNumberInRange(seg["brightness"], prefix+".brightness", errs, 0, 255, "必须是 0–255 的数字")
+	validateColor(seg["color"], prefix+".color", errs)
+
+	mode, _ := seg["mode"].(string)
+	if b, ok := seg["brightness"].(float64); mode != "steady" && ok && b == 0 {
+		add(errs, prefix+".brightness", "brightness=0 仅 steady 模式允许；其它模式会在固件侧被过滤")
+	}
+}
+
+func validatePixelFrame(value any, field string, errs *[]ValidationError) {
+	arr, ok := value.([]any)
+	if !ok {
+		add(errs, field, "pixel_frame 必须提供 pixels 数组（1–7 项）")
+		return
+	}
+	if len(arr) < 1 || len(arr) > 7 {
+		add(errs, field, "pixels 必须为 1–7 项")
+	}
+
+	seen := map[int]bool{}
+	for i, p := range arr {
+		prefix := fmt.Sprintf("%s[%d]", field, i)
+		pixel, ok := p.(map[string]any)
+		if !ok {
+			add(errs, prefix, "必须是对象")
+			continue
+		}
+		idx, idxOK := pixel["index"].(float64)
+		if !idxOK || idx != math.Trunc(idx) || idx < 0 || idx > 6 {
+			add(errs, prefix+".index", "index 必须是 0–6 的整数")
+		} else if seen[int(idx)] {
+			add(errs, prefix+".index", fmt.Sprintf("index=%s 重复", trimNum(idx)))
+		} else {
+			seen[int(idx)] = true
+		}
+		validateNumberInRange(pixel["brightness"], prefix+".brightness", errs, 0, 255, "必须是 0–255 的数字")
+		validateColor(pixel["color"], prefix+".color", errs)
+	}
+}
+
+func validateOptionalBreathTiming(value any, field string, errs *[]ValidationError) {
+	if value == nil {
+		return
+	}
+	bt, ok := value.(map[string]any)
+	if !ok {
+		add(errs, field, "必须是对象")
+		return
+	}
+	validatePositiveNumber(bt["rise_ms"], field+".rise_ms", errs, "rise_ms 必须是 >0 的数字（不支持 0ms）")
+	validateNonNegativeNumber(bt["hold_ms"], field+".hold_ms", errs, "hold_ms 必须是 ≥0 的数字")
+	validatePositiveNumber(bt["fall_ms"], field+".fall_ms", errs, "fall_ms 必须是 >0 的数字（不支持 0ms）")
+	validateNonNegativeNumber(bt["off_ms"], field+".off_ms", errs, "off_ms 必须是 ≥0 的数字")
+}
+
+func validateOptionalBackground(value any, field string, errs *[]ValidationError) {
+	if value == nil {
+		return
+	}
+	bg, ok := value.(map[string]any)
+	if !ok {
+		add(errs, field, "必须包含 r/g/b/brightness 数值")
+		return
+	}
+	validateColor(bg, field, errs)
+	validateNumberInRange(bg["brightness"], field+".brightness", errs, 0, 255, "必须是 0–255 的数字")
+}
+
+func validateOptionalColor(value any, field string, errs *[]ValidationError) {
+	if value == nil {
+		return
+	}
+	validateColor(value, field, errs)
+}
+
+func validateColor(value any, field string, errs *[]ValidationError) {
+	c, ok := value.(map[string]any)
+	if !ok {
+		add(errs, field, "必须包含 r/g/b 数值")
+		return
+	}
+	validateNumberInRange(c["r"], field+".r", errs, 0, 255, "必须是 0–255 的数字")
+	validateNumberInRange(c["g"], field+".g", errs, 0, 255, "必须是 0–255 的数字")
+	validateNumberInRange(c["b"], field+".b", errs, 0, 255, "必须是 0–255 的数字")
+}
+
+func validateOptionalDirection(value any, field string, errs *[]ValidationError) {
+	if value == nil {
+		return
+	}
+	if d, ok := value.(string); !ok || (d != "ltr" && d != "rtl") {
+		add(errs, field, "direction 必须是 ltr 或 rtl")
+	}
+}
+
+func validateOptionalWindow(value any, field string, errs *[]ValidationError) {
+	if value == nil {
+		return
+	}
+	w, ok := value.(float64)
+	if !ok || (w != 1 && w != 2 && w != 3) {
+		add(errs, field, "window 仅支持 1/2/3")
+	}
+}
+
+func validateOptionalNonNegativeNumber(value any, field string, errs *[]ValidationError) {
+	if value == nil {
+		return
+	}
+	validateNonNegativeNumber(value, field, errs, "必须是 ≥0 的数字")
+}
+
+func validatePositiveNumber(value any, field string, errs *[]ValidationError, message string) {
+	if value == nil {
+		return
+	}
+	if n, ok := value.(float64); !ok || !isFinite(n) || n <= 0 {
+		add(errs, field, message)
+	}
+}
+
+func validateNonNegativeNumber(value any, field string, errs *[]ValidationError, message string) {
+	if n, ok := value.(float64); !ok || !isFinite(n) || n < 0 {
+		add(errs, field, message)
+	}
+}
+
+func validateNumberInRange(value any, field string, errs *[]ValidationError, min, max float64, message string) {
+	if n, ok := value.(float64); !ok || !isFinite(n) || n < min || n > max {
+		add(errs, field, message)
+	}
+}
+
+func hasNonZeroRgb(value any) bool {
+	m, ok := value.(map[string]any)
+	if !ok {
+		return false
+	}
+	for _, k := range []string{"r", "g", "b"} {
+		if n, ok := m[k].(float64); ok && isFinite(n) && n > 0 {
+			return true
+		}
+	}
+	return false
+}
+
+// detectColorFlowSingleAnchorMisuse 对「单一极端纯色前景锚点 + 无有效底色」推一条 warning。
+func detectColorFlowSingleAnchorMisuse(seg map[string]any, prefix string, warnings *[]ValidationWarning) {
+	fg := extractChannels(seg["color"])
+	if fg == nil {
+		return
+	}
+	bg := extractChannels(seg["background"])
+	bgBrightness := 0.0
+	if bgm, ok := seg["background"].(map[string]any); ok {
+		if v, ok := bgm["brightness"].(float64); ok && isFinite(v) {
+			bgBrightness = v
+		}
+	}
+	bgActive := bg != nil && anyPositive(bg) && bgBrightness > 0
+	if bgActive {
+		return
+	}
+	var activeFg []float64
+	for _, c := range fg {
+		if c > 0 {
+			activeFg = append(activeFg, c)
+		}
+	}
+	if len(activeFg) != 1 || activeFg[0] < 192 {
+		return
+	}
+	*warnings = append(*warnings, ValidationWarning{
+		Field: prefix,
+		Code:  "COLOR_FLOW_SINGLE_ANCHOR_MISUSE",
+		Message: "color_flow 仅设置了单一极端纯色前景锚点（无有效底色锚点），实际效果是同色系亮暗环状流动，不是多色调色板流动。" +
+			"若用户期望的是\"单色波浪\"，请改用 mode='wave'；若期望多色流动，请同时设置 background 作为第二锚点。",
+	})
+}
+
+func extractChannels(value any) []float64 {
+	m, ok := value.(map[string]any)
+	if !ok {
+		return nil
+	}
+	out := make([]float64, 3)
+	for i, k := range []string{"r", "g", "b"} {
+		if n, ok := m[k].(float64); ok && isFinite(n) {
+			out[i] = n
+		}
+	}
+	return out
+}
+
+func anyPositive(vals []float64) bool {
+	for _, v := range vals {
+		if v > 0 {
+			return true
+		}
+	}
+	return false
+}
+
+func add(errs *[]ValidationError, field, message string) {
+	*errs = append(*errs, ValidationError{Field: field, Message: message})
+}
+
+func contains(list []string, v string) bool {
+	for _, x := range list {
+		if x == v {
+			return true
+		}
+	}
+	return false
+}
+
+func joinSlash(list []string) string {
+	out := ""
+	for i, s := range list {
+		if i > 0 {
+			out += "/"
+		}
+		out += s
+	}
+	return out
+}
+
+func isFinite(v float64) bool {
+	return !math.IsInf(v, 0) && !math.IsNaN(v)
+}
+
+func stringifyMode(v any) string {
+	if v == nil {
+		return "undefined"
+	}
+	return fmt.Sprintf("%v", v)
+}
+
+func trimNum(v float64) string {
+	if v == math.Trunc(v) {
+		return fmt.Sprintf("%d", int(v))
+	}
+	return fmt.Sprintf("%v", v)
+}
diff --git a/internal/lightrule/storage.go b/internal/lightrule/storage.go
new file mode 100644
index 0000000..f151871
--- /dev/null
+++ b/internal/lightrule/storage.go
@@ -0,0 +1,290 @@
+// Package lightrule 提供灯效规则的本地文件存储（meta.json CRUD），
+// 对齐 src/vendor/light-rules/storage.ts。规则落在 <base>/tasks/<name>/meta.json。
+package lightrule
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/YoooClaw/cli/internal/light"
+)
+
+// Error 携带稳定错误码（ALREADY_EXISTS / NOT_FOUND）。
+type Error struct {
+	Code    string
+	Message string
+}
+
+func (e *Error) Error() string { return e.Message }
+
+// Meta 是单条灯效规则元数据（meta.json）。
+type Meta struct {
+	Name        string           `json:"name"`
+	Title       string           `json:"title"`
+	Type        string           `json:"type"`
+	Description string           `json:"description"`
+	Segments    []map[string]any `json:"segments"`
+	RepeatTimes int              `json:"repeat_times"`
+	Enabled     bool             `json:"enabled"`
+	CreatedAt   string           `json:"createdAt"`
+	UpdatedAt   string           `json:"updatedAt,omitempty"`
+}
+
+// CreateParams 是创建规则的入参。
+type CreateParams struct {
+	Name        string
+	Title       string
+	Description string
+	Segments    []map[string]any
+	Repeat      *bool
+	RepeatTimes *float64
+}
+
+// UpdateParams 是更新规则的入参（指针字段为 nil 表示不改）。
+type UpdateParams struct {
+	Name        string
+	Title       *string
+	Description *string
+	Segments    []map[string]any
+	HasSegments bool
+	Repeat      *bool
+	RepeatTimes *float64
+	Enabled     *bool
+}
+
+// 写路径串行化锁（与 TS registry 的 write chain 等价的最朴素 mutex）。
+var writeMu sync.Mutex
+
+func tasksDir(base string) string { return filepath.Join(base, "tasks") }
+
+func normalizeLookupName(name string) string {
+	n := strings.TrimSpace(name)
+	if strings.HasSuffix(strings.ToLower(n), ".json") {
+		n = n[:len(n)-len(".json")]
+	}
+	return n
+}
+
+func readMeta(taskDir string) *Meta {
+	raw, err := os.ReadFile(filepath.Join(taskDir, "meta.json"))
+	if err != nil {
+		return nil
+	}
+	var m map[string]any
+	if json.Unmarshal(raw, &m) != nil {
+		return nil
+	}
+	if t, _ := m["type"].(string); t != "light-rule" {
+		return nil
+	}
+	segsRaw, ok := m["segments"].([]any)
+	if !ok {
+		return nil
+	}
+	segs := make([]map[string]any, 0, len(segsRaw))
+	for _, s := range segsRaw {
+		if sm, ok := s.(map[string]any); ok {
+			segs = append(segs, sm)
+		}
+	}
+
+	name := optStr(m["name"])
+	if name == "" {
+		name = filepath.Base(taskDir)
+	}
+	title := optStr(m["title"])
+	if title == "" {
+		title = name
+	}
+	description := optStr(m["description"])
+	if description == "" {
+		description = name
+	}
+	createdAt := optStr(m["createdAt"])
+	if createdAt == "" {
+		if info, err := os.Stat(filepath.Join(taskDir, "meta.json")); err == nil {
+			createdAt = info.ModTime().UTC().Format(time.RFC3339)
+		}
+	}
+	enabled := true
+	if b, ok := m["enabled"].(bool); ok {
+		enabled = b
+	}
+	repeatTimes, err := light.NormalizeRepeatTimes(light.RepeatInputFromAny(m["repeat"], m["repeat_times"]))
+	if err != nil {
+		return nil
+	}
+	if light.AssertAncsRepeatTimes(repeatTimes) != nil {
+		return nil
+	}
+	updatedAt := optStr(m["updatedAt"])
+
+	return &Meta{
+		Name: name, Title: title, Type: "light-rule", Description: description,
+		Segments: segs, RepeatTimes: repeatTimes, Enabled: enabled,
+		CreatedAt: createdAt, UpdatedAt: updatedAt,
+	}
+}
+
+func writeMeta(taskDir string, m *Meta) error {
+	if err := fsutil.EnsureDir(taskDir, fsutil.DirMode); err != nil {
+		return err
+	}
+	return fsutil.WriteJSON(filepath.Join(taskDir, "meta.json"), m, fsutil.ConfigFileMode)
+}
+
+type resolved struct {
+	taskDir string
+	meta    *Meta
+}
+
+func resolve(base, name string) *resolved {
+	norm := normalizeLookupName(name)
+	if norm == "" {
+		return nil
+	}
+	dir := tasksDir(base)
+	if meta := readMeta(filepath.Join(dir, norm)); meta != nil {
+		return &resolved{taskDir: filepath.Join(dir, norm), meta: meta}
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return nil
+	}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		taskDir := filepath.Join(dir, e.Name())
+		if meta := readMeta(taskDir); meta != nil && meta.Name == norm {
+			return &resolved{taskDir: taskDir, meta: meta}
+		}
+	}
+	return nil
+}
+
+// List 返回全部规则（含 disabled），按目录扫描去重（首个 name 胜出）。
+func List(base string) []Meta {
+	out := []Meta{}
+	seen := map[string]bool{}
+	entries, err := os.ReadDir(tasksDir(base))
+	if err != nil {
+		return out
+	}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		meta := readMeta(filepath.Join(tasksDir(base), e.Name()))
+		if meta == nil || seen[meta.Name] {
+			continue
+		}
+		out = append(out, *meta)
+		seen[meta.Name] = true
+	}
+	return out
+}
+
+// Get 按名精确查找；不存在返回 nil。
+func Get(base, name string) *Meta {
+	if r := resolve(base, name); r != nil {
+		return r.meta
+	}
+	return nil
+}
+
+// Create 创建规则；同名已存在报 ALREADY_EXISTS。
+func Create(base string, p CreateParams) (*Meta, error) {
+	writeMu.Lock()
+	defer writeMu.Unlock()
+
+	if resolve(base, p.Name) != nil {
+		return nil, &Error{Code: "ALREADY_EXISTS", Message: "灯效规则 '" + p.Name + "' 已存在"}
+	}
+	taskDir := filepath.Join(tasksDir(base), p.Name)
+	if fsutil.Exists(taskDir) {
+		return nil, &Error{Code: "ALREADY_EXISTS", Message: "灯效规则 '" + p.Name + "' 已存在"}
+	}
+	repeatTimes, err := light.NormalizeRepeatTimes(light.RepeatInput{Repeat: p.Repeat, RepeatTimes: p.RepeatTimes})
+	if err != nil {
+		return nil, err
+	}
+	if err := light.AssertAncsRepeatTimes(repeatTimes); err != nil {
+		return nil, err
+	}
+	meta := &Meta{
+		Name: p.Name, Title: p.Title, Type: "light-rule", Description: p.Description,
+		Segments: p.Segments, RepeatTimes: repeatTimes, Enabled: true,
+		CreatedAt: time.Now().UTC().Format(time.RFC3339),
+	}
+	if err := writeMeta(taskDir, meta); err != nil {
+		return nil, err
+	}
+	return meta, nil
+}
+
+// Update 更新规则；不存在报 NOT_FOUND。
+func Update(base string, p UpdateParams) (*Meta, error) {
+	writeMu.Lock()
+	defer writeMu.Unlock()
+
+	r := resolve(base, p.Name)
+	if r == nil {
+		return nil, &Error{Code: "NOT_FOUND", Message: "灯效规则 '" + p.Name + "' 不存在"}
+	}
+	meta := r.meta
+	if p.Description != nil {
+		meta.Description = *p.Description
+	}
+	if p.Title != nil {
+		meta.Title = *p.Title
+	}
+	if p.HasSegments {
+		meta.Segments = p.Segments
+	}
+	if p.Repeat != nil || p.RepeatTimes != nil {
+		rt, err := light.NormalizeRepeatTimes(light.RepeatInput{Repeat: p.Repeat, RepeatTimes: p.RepeatTimes})
+		if err != nil {
+			return nil, err
+		}
+		if err := light.AssertAncsRepeatTimes(rt); err != nil {
+			return nil, err
+		}
+		meta.RepeatTimes = rt
+	}
+	if p.Enabled != nil {
+		meta.Enabled = *p.Enabled
+	}
+	meta.UpdatedAt = time.Now().UTC().Format(time.RFC3339)
+	if err := writeMeta(r.taskDir, meta); err != nil {
+		return nil, err
+	}
+	return meta, nil
+}
+
+// Delete 删除规则；不存在报 NOT_FOUND。
+func Delete(base, name string) (string, error) {
+	writeMu.Lock()
+	defer writeMu.Unlock()
+
+	r := resolve(base, name)
+	if r == nil {
+		return "", &Error{Code: "NOT_FOUND", Message: "灯效规则 '" + name + "' 不存在"}
+	}
+	if err := os.RemoveAll(r.taskDir); err != nil {
+		return "", err
+	}
+	return r.meta.Name, nil
+}
+
+func optStr(v any) string {
+	if s, ok := v.(string); ok {
+		return strings.TrimSpace(s)
+	}
+	return ""
+}

From 6db1de3059018a4183e0c72828bf6b1af3edaed4 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 19:12:08 +0800
Subject: [PATCH 08/13] feat(go): add recording ingest and relay tunnel

---
 go.mod                                   |   1 +
 go.sum                                   |   2 +
 internal/daemon/server.go                | 149 +++++-
 internal/daemon/server_gateway_compat.go |  83 +++
 internal/daemon/server_ingest.go         | 398 ++++++++++++++
 internal/daemon/server_services.go       |  69 ++-
 internal/image/store.go                  | 169 ++++++
 internal/image/store_test.go             |  78 +++
 internal/recording/asr.go                | 641 +++++++++++++++++++++++
 internal/recording/downloader.go         | 133 +++++
 internal/recording/events.go             |  54 ++
 internal/recording/handler.go            | 224 ++++++++
 internal/recording/handler_test.go       | 161 ++++++
 internal/recording/state.go              |  62 +++
 internal/recording/store.go              | 455 +++++++++++++++-
 internal/recording/transcript.go         | 231 ++++++++
 internal/relay/client.go                 | 482 +++++++++++++++++
 internal/relay/dispatcher.go             | 372 +++++++++++++
 internal/relay/dispatcher_test.go        | 159 ++++++
 internal/relay/supervisor.go             | 197 +++++++
 internal/relay/types.go                  | 122 +++++
 21 files changed, 4199 insertions(+), 43 deletions(-)
 create mode 100644 internal/daemon/server_gateway_compat.go
 create mode 100644 internal/daemon/server_ingest.go
 create mode 100644 internal/image/store_test.go
 create mode 100644 internal/recording/asr.go
 create mode 100644 internal/recording/downloader.go
 create mode 100644 internal/recording/events.go
 create mode 100644 internal/recording/handler.go
 create mode 100644 internal/recording/handler_test.go
 create mode 100644 internal/recording/state.go
 create mode 100644 internal/recording/transcript.go
 create mode 100644 internal/relay/client.go
 create mode 100644 internal/relay/dispatcher.go
 create mode 100644 internal/relay/dispatcher_test.go
 create mode 100644 internal/relay/supervisor.go
 create mode 100644 internal/relay/types.go

diff --git a/go.mod b/go.mod
index f950f13..18a7c52 100644
--- a/go.mod
+++ b/go.mod
@@ -5,6 +5,7 @@ go 1.26.4
 require github.com/spf13/cobra v1.10.2
 
 require (
+	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
 )
diff --git a/go.sum b/go.sum
index a6ee3e0..34e2208 100644
--- a/go.sum
+++ b/go.sum
@@ -1,4 +1,6 @@
 github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
diff --git a/internal/daemon/server.go b/internal/daemon/server.go
index f6a37ba..caf7857 100644
--- a/internal/daemon/server.go
+++ b/internal/daemon/server.go
@@ -19,14 +19,16 @@ import (
 	"github.com/YoooClaw/cli/internal/errs"
 	"github.com/YoooClaw/cli/internal/fsutil"
 	"github.com/YoooClaw/cli/internal/notif"
+	"github.com/YoooClaw/cli/internal/recording"
+	"github.com/YoooClaw/cli/internal/relay"
 	"github.com/YoooClaw/cli/internal/version"
 )
 
 // ProtocolVersion 是手机端协议协商版本。
 const ProtocolVersion = 1
 
-// Capabilities 是本 build 支持的能力（Phase 2 标准 HTTP，relay/recordings/images 待后续）。
-var Capabilities = []string{"notifications", "multi-apikey"}
+// Capabilities 是本 build 支持的 daemon/Relay 能力。
+var Capabilities = []string{"notifications", "recordings", "images", "lightrules", "multi-apikey"}
 
 // StartOpts 是 daemon 启动参数。
 type StartOpts struct {
@@ -77,6 +79,11 @@ func RunForeground(ctx *clictx.Context, opts StartOpts) error {
 	if err := storage.Init(); err != nil {
 		return err
 	}
+	recordingStorage := recording.NewStorage(ctx.Paths.Recordings, logger)
+	if err := recordingStorage.Init(); err != nil {
+		return err
+	}
+	recordingEventLog := recording.NewEventLog(ctx.Paths.Recordings)
 	ignored := map[string]bool{}
 	for _, a := range cfg.Notification.IgnoredApps {
 		ignored[a] = true
@@ -84,7 +91,9 @@ func RunForeground(ctx *clictx.Context, opts StartOpts) error {
 
 	srv := &server{
 		ctx: ctx, cfg: cfg, logger: logger, st: st, storage: storage,
-		token: token, credentialSet: credentialSet, ignored: ignored, bind: bind,
+		recordingStorage: recordingStorage, recordingEventLog: recordingEventLog,
+		recordingInFlight: map[string]time.Time{},
+		token:             token, credentialSet: credentialSet, ignored: ignored, bind: bind,
 	}
 
 	// 监听；端口被占自动 +1（最多 64 次）。
@@ -100,13 +109,30 @@ func RunForeground(ctx *clictx.Context, opts StartOpts) error {
 	}
 	logger.Info(fmt.Sprintf("yoooclaw daemon 启动：%s:%d（profile=%s, pid=%d）", bind, actualPort, ctx.Profile, os.Getpid()))
 	if cfg.Relay.Enabled {
-		logger.Warn("Relay 已启用，但本 build 暂未实现隧道（Phase 3）；当前仅直连 HTTP")
+		if len(credentialSet.Entries) == 0 {
+			logger.Warn("Relay 已启用但未设置 api-key；当前仅直连 HTTP")
+		} else {
+			srv.tunnelSupervisor = relay.NewSupervisor(relay.SupervisorOptions{
+				TunnelURL:          cfg.Relay.URL,
+				HTTPBaseURL:        "http://127.0.0.1:" + fmt.Sprint(actualPort),
+				HTTPToken:          token,
+				HeartbeatSec:       cfg.Relay.HeartbeatSec,
+				ReconnectBackoffMs: cfg.Relay.ReconnectBackoffMs,
+				StateDir:           ctx.Paths.Dir,
+				Logger:             logger,
+			})
+			result := srv.tunnelSupervisor.Apply(credentialSet)
+			logger.Info(fmt.Sprintf("Relay tunnels applied: started=%v unchanged=%v", result.Started, result.Unchanged))
+		}
 	}
 
 	stop := make(chan os.Signal, 1)
 	signal.Notify(stop, syscall.SIGTERM, syscall.SIGINT)
 	srv.shutdown = func(reason string) {
 		logger.Info("daemon 退出（" + reason + "）")
+		if srv.tunnelSupervisor != nil {
+			srv.tunnelSupervisor.StopAll(reason)
+		}
 		_ = httpSrv.Close()
 		RemoveLock(ctx.Paths)
 		os.Exit(0)
@@ -126,17 +152,22 @@ func RunForeground(ctx *clictx.Context, opts StartOpts) error {
 }
 
 type server struct {
-	ctx           *clictx.Context
-	cfg           config.Config
-	logger        *Logger
-	st            *runtimeState
-	storage       *notif.Storage
-	token         string
-	credentialSet creds.CredentialSet
-	ignored       map[string]bool
-	bind          string
-	port          int
-	shutdown      func(string)
+	ctx               *clictx.Context
+	cfg               config.Config
+	logger            *Logger
+	st                *runtimeState
+	storage           *notif.Storage
+	recordingStorage  *recording.Storage
+	recordingEventLog *recording.EventLog
+	recordingMu       sync.Mutex
+	recordingInFlight map[string]time.Time
+	tunnelSupervisor  *relay.Supervisor
+	token             string
+	credentialSet     creds.CredentialSet
+	ignored           map[string]bool
+	bind              string
+	port              int
+	shutdown          func(string)
 }
 
 func (s *server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
@@ -168,17 +199,49 @@ func (s *server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		go func() { time.Sleep(50 * time.Millisecond); s.shutdown("stop-endpoint") }()
 	case path == "/daemon/reload" && r.Method == http.MethodPost:
 		s.credentialSet = creds.ResolveAPIKeyEntries()
-		writeJSON(w, 200, map[string]any{"ok": true, "running": true, "reloaded": true, "mode": s.credentialSet.Mode})
+		relayResult := relay.ApplyResult{}
+		if s.cfg.Relay.Enabled {
+			if s.tunnelSupervisor == nil && len(s.credentialSet.Entries) > 0 {
+				s.tunnelSupervisor = relay.NewSupervisor(relay.SupervisorOptions{
+					TunnelURL:          s.cfg.Relay.URL,
+					HTTPBaseURL:        "http://127.0.0.1:" + fmt.Sprint(s.port),
+					HTTPToken:          s.token,
+					HeartbeatSec:       s.cfg.Relay.HeartbeatSec,
+					ReconnectBackoffMs: s.cfg.Relay.ReconnectBackoffMs,
+					StateDir:           s.ctx.Paths.Dir,
+					Logger:             s.logger,
+				})
+			}
+			if s.tunnelSupervisor != nil {
+				relayResult = s.tunnelSupervisor.Apply(s.credentialSet)
+			}
+		}
+		writeJSON(w, 200, map[string]any{
+			"ok": true, "running": true, "reloaded": true, "mode": s.credentialSet.Mode,
+			"defaultLabel": defaultEntryLabel(s.credentialSet), "warnings": s.credentialSet.Warnings,
+			"started": relayResult.Started, "stopped": relayResult.Stopped,
+			"restarted": relayResult.Restarted, "unchanged": relayResult.Unchanged,
+		})
 	case path == "/notifications" && r.Method == http.MethodPost:
 		s.handleIngest(w, r, authCtx, "notifications")
 	case path == "/gateway/notifications.push" && r.Method == http.MethodPost:
 		s.handleIngest(w, r, authCtx, "items")
+	case path == "/recordings" && r.Method == http.MethodPost:
+		s.handleRecordingHTTP(w, r, authCtx)
+	case strings.HasPrefix(path, "/gateway/recordings.") && r.Method == http.MethodPost:
+		s.handleRecordingGateway(w, r, path, authCtx)
+	case path == "/images" && r.Method == http.MethodPost:
+		s.handleImageHTTP(w, r, authCtx)
+	case path == "/gateway/images.sync" && r.Method == http.MethodPost:
+		s.handleImageGateway(w, r, authCtx)
 	case path == "/monitors" || strings.HasPrefix(path, "/monitors/"):
 		s.handleMonitors(w, r, path)
 	case path == "/light/send" && r.Method == http.MethodPost:
 		s.handleLightSend(w, r)
 	case strings.HasPrefix(path, "/gateway/lightrules."):
 		s.handleLightrules(w, r, path)
+	case strings.HasPrefix(path, "/gateway/") && r.Method == http.MethodPost:
+		s.handleGatewayCompat(w, r, path)
 	case strings.HasPrefix(path, "/tunnel/"):
 		s.handleTunnel(w, r, path)
 	default:
@@ -193,6 +256,12 @@ type authResult struct {
 
 func (s *server) authContext(r *http.Request, path string) (authResult, bool) {
 	bearer := bearerValue(r)
+	internalRelay := r.Header.Get(relay.InternalHTTPHeader) == "1"
+	internalLabel := strings.TrimSpace(r.Header.Get(relay.InternalClientLabelHeader))
+	gatewayTokenOK := s.token == "" || bearer == s.token
+	if internalRelay && internalLabel != "" && gatewayTokenOK {
+		return authResult{clientLabel: internalLabel, authKind: "relay-api-key"}, true
+	}
 	if s.token != "" && bearer == s.token {
 		return authResult{clientLabel: "local", authKind: "gateway-token"}, true
 	}
@@ -277,19 +346,52 @@ func (s *server) handleStatus(w http.ResponseWriter) {
 	if s.credentialSet.DefaultEntry != nil {
 		defaultLabel = s.credentialSet.DefaultEntry.Label
 	}
+	relayStatus := s.relayStatusPayload()
 	writeJSON(w, 200, map[string]any{
 		"ok": true, "server": "yoooclaw", "version": version.Version, "pid": os.Getpid(),
 		"profile": s.ctx.Profile, "bind": s.bind, "port": s.port, "startedAt": s.st.startedAt,
 		"lastIngestAt": nilIfEmptyStr(lastIngest), "ingestCount": ingestCount,
-		"relay": map[string]any{
-			"mode": "standalone-http", "connected": false, "url": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
-			"note": "本 build 未实现 Relay 隧道（Phase 3），仅直连 HTTP",
-		},
+		"relay":          relayStatus,
+		"tunnels":        relayStatus["tunnels"],
 		"credentialMode": s.credentialSet.Mode, "defaultLabel": defaultLabel,
 		"credentialWarnings": s.credentialSet.Warnings,
 	})
 }
 
+func (s *server) relayStatusPayload() map[string]any {
+	if s.tunnelSupervisor != nil {
+		status := s.tunnelSupervisor.Status()
+		connected := false
+		reconnectAttempt := 0
+		lastDisconnectReason := ""
+		for _, tunnel := range status.Tunnels {
+			if tunnel.Default || status.DefaultLabel == "" {
+				connected = tunnel.Connected
+				reconnectAttempt = tunnel.ReconnectAttempt
+				lastDisconnectReason = tunnel.LastDisconnectReason
+				break
+			}
+		}
+		note := any(nil)
+		if !connected {
+			note = "Relay 重连中"
+		}
+		return map[string]any{
+			"mode": "relay", "connected": connected, "url": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
+			"reconnectAttempt": reconnectAttempt, "lastDisconnectReason": nilIfEmptyStr(lastDisconnectReason),
+			"note": note, "tunnels": status.Tunnels,
+		}
+	}
+	note := "Relay 未启用，走直连 HTTP"
+	if s.cfg.Relay.Enabled {
+		note = "Relay 已启用但当前 CredentialSet 没有可用 api-key"
+	}
+	return map[string]any{
+		"mode": "standalone-http", "connected": false, "url": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
+		"reconnectAttempt": 0, "note": note, "tunnels": []any{},
+	}
+}
+
 // ── helpers ──
 
 func isIngestPath(path string) bool {
@@ -355,3 +457,10 @@ func nilIfEmptyStr(s string) any {
 	}
 	return s
 }
+
+func defaultEntryLabel(set creds.CredentialSet) any {
+	if set.DefaultEntry == nil {
+		return nil
+	}
+	return set.DefaultEntry.Label
+}
diff --git a/internal/daemon/server_gateway_compat.go b/internal/daemon/server_gateway_compat.go
new file mode 100644
index 0000000..72accdf
--- /dev/null
+++ b/internal/daemon/server_gateway_compat.go
@@ -0,0 +1,83 @@
+package daemon
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/YoooClaw/cli/internal/version"
+)
+
+func (s *server) handleGatewayCompat(w http.ResponseWriter, r *http.Request, path string) {
+	method := strings.TrimPrefix(path, "/gateway/")
+	switch method {
+	case "health":
+		gatewayOK(w, s.gatewayHealthPayload())
+	case "channels.status":
+		gatewayOK(w, s.gatewayChannelsPayload())
+	case "agents.list":
+		gatewayOK(w, map[string]any{"total": 0, "agents": []any{}, "items": []any{}})
+	case "sessions.list":
+		gatewayOK(w, map[string]any{"total": 0, "sessions": []any{}, "items": []any{}})
+	case "chat.history":
+		var body map[string]any
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		sessionKey, _ := body["sessionKey"].(string)
+		gatewayOK(w, map[string]any{"sessionKey": nilIfEmptyStr(sessionKey), "total": 0, "messages": []any{}})
+	case "usage.cost":
+		gatewayOK(w, map[string]any{"totalCost": 0, "cost": 0, "currency": "USD", "items": []any{}, "usage": []any{}})
+	case "cron.list":
+		gatewayOK(w, map[string]any{"total": 0, "crons": []any{}, "tasks": []any{}, "items": []any{}})
+	case "wake":
+		gatewayOK(w, map[string]any{"ok": true, "woken": true})
+	default:
+		gatewayErr(w, "METHOD_NOT_FOUND", "未注册的 gateway 方法："+method)
+	}
+}
+
+func (s *server) gatewayHealthPayload() map[string]any {
+	relayStatus := s.relayStatusPayload()
+	s.st.mu.Lock()
+	lastIngest := s.st.lastIngest
+	ingestCount := s.st.ingestCount
+	s.st.mu.Unlock()
+	return map[string]any{
+		"status": "ok", "healthy": true, "server": "yoooclaw", "version": version.Version,
+		"protocol": ProtocolVersion, "capabilities": Capabilities, "profile": s.ctx.Profile,
+		"bind": s.bind, "port": s.port, "startedAt": s.st.startedAt,
+		"lastIngestAt": nilIfEmptyStr(lastIngest), "ingestCount": ingestCount,
+		"relay":    relayStatus,
+		"features": map[string]any{"methods": gatewayMethodNames(), "capabilities": Capabilities},
+	}
+}
+
+func (s *server) gatewayChannelsPayload() map[string]any {
+	relayStatus := s.relayStatusPayload()
+	account := map[string]any{
+		"id": "yoooclaw.daemon/" + s.ctx.Profile, "channel": "yoooclaw.daemon",
+		"accountId": s.ctx.Profile, "label": "YoooClaw daemon (" + s.ctx.Profile + ")",
+		"enabled": true, "running": true, "connected": relayStatus["connected"],
+		"mode": relayStatus["mode"], "url": relayStatus["url"], "lastError": relayStatus["lastDisconnectReason"],
+	}
+	return map[string]any{
+		"channelOrder": []string{"yoooclaw.daemon"},
+		"channelMeta":  []map[string]any{{"id": "yoooclaw.daemon", "label": "YoooClaw daemon", "type": "daemon"}},
+		"channels": []map[string]any{{
+			"id": "yoooclaw.daemon", "label": "YoooClaw daemon", "enabled": true,
+			"running": true, "connected": relayStatus["connected"], "accounts": []any{account},
+		}},
+		"accounts": []any{account},
+		"relay":    relayStatus,
+	}
+}
+
+func gatewayMethodNames() []string {
+	return []string{
+		"agents.list", "channels.status", "chat.history", "cron.list", "health",
+		"lightrules.create", "lightrules.delete", "lightrules.list", "lightrules.update",
+		"notifications.push", "recordings.asr.init", "recordings.delete", "recordings.list",
+		"recordings.rename", "recordings.retranscribe", "recordings.status", "recordings.sync",
+		"sessions.list", "usage.cost", "wake",
+	}
+}
diff --git a/internal/daemon/server_ingest.go b/internal/daemon/server_ingest.go
new file mode 100644
index 0000000..6db6772
--- /dev/null
+++ b/internal/daemon/server_ingest.go
@@ -0,0 +1,398 @@
+package daemon
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	imgstore "github.com/YoooClaw/cli/internal/image"
+	"github.com/YoooClaw/cli/internal/recording"
+)
+
+const recordingInFlightTimeout = 5 * time.Minute
+
+var terminalRecordingStatuses = map[string]bool{
+	recording.StatusSynced:           true,
+	recording.StatusTranscribed:      true,
+	recording.StatusTranscribeFailed: true,
+	recording.StatusSyncFailed:       true,
+}
+
+var successfulRecordingStatuses = map[string]bool{
+	recording.StatusSynced:      true,
+	recording.StatusTranscribed: true,
+}
+
+type recordingSyncBody struct {
+	RecordingID string               `json:"recordingId"`
+	Recording   recording.Metadata   `json:"recording"`
+	ASR         *recording.AsrConfig `json:"asr,omitempty"`
+}
+
+type recordingIDBody struct {
+	RecordingID string               `json:"recordingId"`
+	ASR         *recording.AsrConfig `json:"asr,omitempty"`
+}
+
+func (s *server) handleRecordingHTTP(w http.ResponseWriter, r *http.Request, auth authResult) {
+	var body recordingSyncBody
+	if !decodeBody(w, r, &body) {
+		return
+	}
+	result, ok, code, message := s.doRecordingSync(body, auth.clientLabel)
+	if !ok {
+		writeJSON(w, 400, map[string]any{"ok": false, "error": message})
+		return
+	}
+	status := 200
+	if !result.OK {
+		status = 500
+	}
+	_ = code
+	writeJSON(w, status, result)
+}
+
+func (s *server) handleRecordingGateway(w http.ResponseWriter, r *http.Request, path string, auth authResult) {
+	method := strings.TrimPrefix(path, "/gateway/")
+	switch method {
+	case "recordings.sync":
+		var body recordingSyncBody
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		result, ok, code, message := s.doRecordingSync(body, auth.clientLabel)
+		if !ok {
+			gatewayErr(w, code, message)
+			return
+		}
+		if result.OK {
+			gatewayOK(w, result)
+		} else {
+			gatewayErr(w, "SYNC_FAILED", firstNonEmptyStr(result.Error, "Unknown error"))
+		}
+
+	case "recordings.retranscribe":
+		var body recordingIDBody
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		recordingID := strings.TrimSpace(body.RecordingID)
+		if recordingID == "" {
+			gatewayErr(w, "INVALID_PARAMS", "recordingId is required")
+			return
+		}
+		if body.ASR != nil {
+			if errMsg := recording.ValidateAsrConfig(body.ASR); errMsg != "" {
+				gatewayErr(w, "ASR_NOT_CONFIGURED", errMsg)
+				return
+			}
+		}
+		asr := s.resolveConfiguredASR(body.ASR)
+		if errMsg := recording.ValidateAsrConfig(asr); errMsg != "" {
+			gatewayErr(w, "ASR_NOT_CONFIGURED", errMsg)
+			return
+		}
+		entry, ok := s.recordingStorage.FindByID(recordingID)
+		if !ok {
+			gatewayErr(w, "NOT_FOUND", "Recording not found: "+recordingID)
+			return
+		}
+		if !recording.CanStartTranscription(entry.Status) {
+			gatewayErr(w, "INVALID_STATE", "Recording status does not allow retranscribe: "+entry.Status)
+			return
+		}
+		if body.ASR == nil {
+			s.logger.Info("[recording-retranscribe] 使用本地 asr-config.json（mode=" + asr.Mode + maskedKeyLog(asr) + "）")
+		}
+		go func() {
+			if err := recording.TriggerTranscription(recordingID, s.recordingStorage, *asr, s.logger, recording.SyncOptions{
+				NotifyStatus: s.notifyRecordingStatus,
+			}); err != nil {
+				s.logger.Error("[recording-retranscribe] 重试转写失败: " + recordingID + ", " + err.Error())
+			}
+		}()
+		gatewayOK(w, map[string]any{"ok": true, "recordingId": recordingID, "message": "转写已重新触发"})
+
+	case "recordings.asr.init":
+		var body struct {
+			ASR *recording.AsrConfig `json:"asr"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		asr := s.resolveConfiguredASR(body.ASR)
+		result := recording.InitializeAsr(asr)
+		if !result.OK {
+			gatewayErr(w, "ASR_INIT_FAILED", result.Error)
+			return
+		}
+		gatewayOK(w, result)
+
+	case "recordings.list":
+		var body struct {
+			Status string `json:"status"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		status := strings.TrimSpace(body.Status)
+		if status != "" && !recording.IsRecordingStatus(status) {
+			gatewayErr(w, "INVALID_PARAMS", "invalid recording status: "+status)
+			return
+		}
+		entries := s.recordingStorage.ListAll()
+		if status != "" {
+			entries = s.recordingStorage.ListByStatus(status)
+		}
+		items := make([]map[string]any, 0, len(entries))
+		for _, entry := range entries {
+			items = append(items, recordingListItem(entry))
+		}
+		gatewayOK(w, map[string]any{"total": len(items), "recordings": items})
+
+	case "recordings.status":
+		var body recordingIDBody
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		recordingID := strings.TrimSpace(body.RecordingID)
+		if recordingID == "" {
+			gatewayErr(w, "INVALID_PARAMS", "recordingId is required")
+			return
+		}
+		entry, ok := s.recordingStorage.FindByID(recordingID)
+		if !ok {
+			gatewayErr(w, "NOT_FOUND", "Recording not found: "+recordingID)
+			return
+		}
+		gatewayOK(w, recordingDetail(entry))
+
+	case "recordings.rename":
+		var body struct {
+			RecordingID string `json:"recordingId"`
+			Name        string `json:"name"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		recordingID := strings.TrimSpace(body.RecordingID)
+		name := strings.TrimSpace(body.Name)
+		if recordingID == "" || name == "" {
+			gatewayErr(w, "INVALID_PARAMS", "recordingId and name are required")
+			return
+		}
+		entry, ok, err := s.recordingStorage.Rename(recordingID, name)
+		if err != nil {
+			gatewayErr(w, "INTERNAL_ERROR", err.Error())
+			return
+		}
+		if !ok {
+			gatewayErr(w, "NOT_FOUND", "Recording not found: "+recordingID)
+			return
+		}
+		gatewayOK(w, recordingDetail(entry))
+
+	case "recordings.delete":
+		var body struct {
+			RecordingID  string `json:"recordingId"`
+			DeleteRemote bool   `json:"deleteRemote"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		recordingID := strings.TrimSpace(body.RecordingID)
+		if recordingID == "" {
+			gatewayErr(w, "INVALID_PARAMS", "recordingId is required")
+			return
+		}
+		deleted, err := s.recordingStorage.Delete(recordingID, !body.DeleteRemote)
+		if err != nil {
+			gatewayErr(w, "INTERNAL_ERROR", err.Error())
+			return
+		}
+		if !deleted {
+			gatewayErr(w, "NOT_FOUND", "Recording not found: "+recordingID)
+			return
+		}
+		gatewayOK(w, map[string]any{"ok": true, "recordingId": recordingID, "deletedRemote": body.DeleteRemote})
+
+	default:
+		writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
+	}
+}
+
+func (s *server) doRecordingSync(body recordingSyncBody, clientLabel string) (recording.SyncResult, bool, string, string) {
+	recordingID := strings.TrimSpace(body.RecordingID)
+	if recordingID == "" {
+		return recording.SyncResult{}, false, "INVALID_PARAMS", "recordingId is required"
+	}
+	if strings.TrimSpace(body.Recording.OssAudioURL) == "" || strings.TrimSpace(body.Recording.CreatedAt) == "" {
+		return recording.SyncResult{}, false, "INVALID_PARAMS", "recording with oss_audio_url and created_at is required"
+	}
+	if body.ASR != nil {
+		if errMsg := recording.ValidateAsrConfig(body.ASR); errMsg != "" {
+			return recording.SyncResult{}, false, "INVALID_PARAMS", errMsg
+		}
+	}
+	if s.isRecordingInFlight(recordingID) {
+		entry, ok := s.recordingStorage.FindByID(recordingID)
+		status := recording.StatusSyncingOpenClaw
+		if ok {
+			status = entry.Status
+		}
+		s.logger.Info("[recording-sync] in-flight 跳过重复 sync: " + recordingID + "（当前 " + status + "）")
+		return recording.SyncResult{OK: true, RecordingID: recordingID, TransferStatus: status}, true, "", ""
+	}
+	asr := s.resolveConfiguredASR(body.ASR)
+	if asr != nil && body.ASR == nil {
+		s.logger.Info("[recording-sync] 使用本地 asr-config.json（mode=" + asr.Mode + maskedKeyLog(asr) + "）")
+	}
+	s.markRecordingInFlight(recordingID)
+	result := recording.HandleRecordingSyncWithClientLabel(recordingID, body.Recording, clientLabel, s.recordingStorage, asr, s.logger, recording.SyncOptions{
+		NotifyStatus: s.notifyRecordingStatus,
+	})
+	if !result.OK {
+		s.releaseRecordingInFlight(recordingID)
+	}
+	return result, true, "", ""
+}
+
+func (s *server) handleImageHTTP(w http.ResponseWriter, r *http.Request, auth authResult) {
+	var body imgstore.SyncPayload
+	if !decodeBody(w, r, &body) {
+		return
+	}
+	result, err := imgstore.Ingest(s.ctx.Paths.Images, body, auth.clientLabel, s.cfg.Image.MaxBytes, s.logger)
+	if err != nil {
+		writeJSON(w, 400, errBody("INVALID_PARAMS", err.Error()))
+		return
+	}
+	writeJSON(w, 200, result)
+}
+
+func (s *server) handleImageGateway(w http.ResponseWriter, r *http.Request, auth authResult) {
+	var body imgstore.SyncPayload
+	if !decodeBody(w, r, &body) {
+		return
+	}
+	result, err := imgstore.Ingest(s.ctx.Paths.Images, body, auth.clientLabel, s.cfg.Image.MaxBytes, s.logger)
+	if err != nil {
+		gatewayErr(w, "INVALID_PARAMS", err.Error())
+		return
+	}
+	gatewayOK(w, result)
+}
+
+func (s *server) resolveConfiguredASR(caller *recording.AsrConfig) *recording.AsrConfig {
+	fallback := ""
+	if s.credentialSet.DefaultEntry != nil {
+		fallback = s.credentialSet.DefaultEntry.Key
+	}
+	return recording.ResolveAsrConfig(caller, recording.LoadLocalAsrConfig(s.ctx.Paths.Recordings), fallback)
+}
+
+func (s *server) notifyRecordingStatus(event recording.StatusEvent) {
+	s.logger.Info("[recording-status] " + event.RecordingID + " -> " + event.TransferStatus + errorSuffix(event.Error))
+	if s.recordingEventLog != nil {
+		if err := s.recordingEventLog.Append(event); err != nil {
+			s.logger.Warn("[recording-status] 事件落盘失败: " + err.Error())
+		}
+	}
+	if s.tunnelSupervisor != nil {
+		s.tunnelSupervisor.PushEvent("recording.status", event)
+	}
+	if terminalRecordingStatuses[event.TransferStatus] {
+		s.releaseRecordingInFlight(event.RecordingID)
+	}
+	if successfulRecordingStatuses[event.TransferStatus] {
+		if entry, ok := s.recordingStorage.FindByID(event.RecordingID); ok && entry.LastError != "" {
+			_ = s.recordingStorage.SetLastError(event.RecordingID, "")
+			s.logger.Info("[recording-sync] 终态 " + event.TransferStatus + " 清理 lastError 残留: " + event.RecordingID)
+		}
+	}
+}
+
+func (s *server) markRecordingInFlight(recordingID string) {
+	s.recordingMu.Lock()
+	defer s.recordingMu.Unlock()
+	s.recordingInFlight[recordingID] = time.Now().Add(recordingInFlightTimeout)
+}
+
+func (s *server) releaseRecordingInFlight(recordingID string) {
+	s.recordingMu.Lock()
+	defer s.recordingMu.Unlock()
+	delete(s.recordingInFlight, recordingID)
+}
+
+func (s *server) isRecordingInFlight(recordingID string) bool {
+	s.recordingMu.Lock()
+	defer s.recordingMu.Unlock()
+	deadline, ok := s.recordingInFlight[recordingID]
+	if !ok {
+		return false
+	}
+	if time.Now().After(deadline) {
+		delete(s.recordingInFlight, recordingID)
+		return false
+	}
+	return true
+}
+
+func recordingListItem(entry recording.Entry) map[string]any {
+	return map[string]any{
+		"recordingId":        entry.ID,
+		"name":               entry.Metadata.Name,
+		"duration_sec":       entry.Metadata.DurationSec,
+		"file_size_bytes":    entry.Metadata.FileSizeBytes,
+		"created_at":         entry.Metadata.CreatedAt,
+		"transfer_status":    entry.Status,
+		"marker_count":       len(entry.Metadata.Markers),
+		"has_audio":          entry.AudioFile != "",
+		"has_srt":            entry.SrtFile != "",
+		"has_transcript":     entry.TranscriptFile != "",
+		"audioFile":          nilIfEmptyStr(entry.AudioFile),
+		"transcriptDataFile": nilIfEmptyStr(entry.TranscriptDataFile),
+		"transcriptFile":     nilIfEmptyStr(entry.TranscriptFile),
+		"updatedAt":          entry.UpdatedAt,
+		"error":              nilIfEmptyStr(entry.LastError),
+	}
+}
+
+func recordingDetail(entry recording.Entry) map[string]any {
+	title := firstNonEmptyStr(entry.Title, entry.Metadata.Name, entry.ID)
+	return map[string]any{
+		"recordingId":        entry.ID,
+		"name":               entry.Metadata.Name,
+		"duration_sec":       entry.Metadata.DurationSec,
+		"file_size_bytes":    entry.Metadata.FileSizeBytes,
+		"created_at":         entry.Metadata.CreatedAt,
+		"location":           entry.Metadata.Location,
+		"oss_audio_url":      entry.Metadata.OssAudioURL,
+		"oss_srt_url":        nilIfEmptyStr(entry.Metadata.OssSrtURL),
+		"markers":            entry.Metadata.Markers,
+		"transfer_status":    entry.Status,
+		"audioFile":          nilIfEmptyStr(entry.AudioFile),
+		"srtFile":            nilIfEmptyStr(entry.SrtFile),
+		"transcriptDataFile": nilIfEmptyStr(entry.TranscriptDataFile),
+		"transcriptFile":     nilIfEmptyStr(entry.TranscriptFile),
+		"summaryFile":        nilIfEmptyStr(entry.SummaryFile),
+		"title":              title,
+		"ingestedAt":         entry.IngestedAt,
+		"updatedAt":          entry.UpdatedAt,
+		"error":              nilIfEmptyStr(entry.LastError),
+	}
+}
+
+func maskedKeyLog(asr *recording.AsrConfig) string {
+	if asr != nil && asr.API != nil && strings.TrimSpace(asr.API.APIKey) != "" {
+		return ", key=ock-***"
+	}
+	return ""
+}
+
+func errorSuffix(err string) string {
+	if err == "" {
+		return ""
+	}
+	return " err=" + err
+}
diff --git a/internal/daemon/server_services.go b/internal/daemon/server_services.go
index 74d6e16..c2b483c 100644
--- a/internal/daemon/server_services.go
+++ b/internal/daemon/server_services.go
@@ -10,6 +10,7 @@ import (
 
 	"github.com/YoooClaw/cli/internal/monitor"
 	"github.com/YoooClaw/cli/internal/notif"
+	"github.com/YoooClaw/cli/internal/relay"
 )
 
 // handleMonitors 处理 /monitors 与 /monitors/<name>[/enable|disable]。
@@ -57,32 +58,80 @@ func (s *server) handleMonitors(w http.ResponseWriter, r *http.Request, path str
 	}
 }
 
-// handleTunnel 处理 /tunnel/*。本 build 无 Relay 隧道（Phase 3），返回 standalone 语义。
+// handleTunnel 处理 /tunnel/*。
 func (s *server) handleTunnel(w http.ResponseWriter, r *http.Request, path string) {
-	note := "Relay 隧道未实现（Phase 3）；当前仅直连 HTTP"
 	switch path {
 	case "/tunnel/status":
+		relayStatus := s.relayStatusPayload()
+		client := strings.TrimSpace(r.URL.Query().Get("client"))
+		if client != "" && client != "all" {
+			relayStatus["tunnels"] = filterRelayTunnels(relayStatus["tunnels"], client)
+		}
 		writeJSON(w, 200, map[string]any{
-			"ok": true, "mode": "standalone-http", "credentialMode": s.credentialSet.Mode,
-			"connected": false, "relayUrl": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
-			"note": note, "tunnels": []any{},
+			"ok": true, "mode": relayStatus["mode"], "credentialMode": s.credentialSet.Mode,
+			"defaultLabel": defaultEntryLabel(s.credentialSet),
+			"connected":    relayStatus["connected"], "relayUrl": s.cfg.Relay.URL, "enabled": s.cfg.Relay.Enabled,
+			"reconnectAttempt": relayStatus["reconnectAttempt"], "lastDisconnectReason": relayStatus["lastDisconnectReason"],
+			"note": relayStatus["note"], "tunnels": relayStatus["tunnels"],
 		})
 	case "/tunnel/reconnect":
-		writeJSON(w, 200, map[string]any{"ok": true, "mode": "standalone-http", "reconnected": false, "note": note})
+		if s.tunnelSupervisor == nil {
+			relayStatus := s.relayStatusPayload()
+			writeJSON(w, 200, map[string]any{"ok": true, "mode": relayStatus["mode"], "reconnected": false, "note": relayStatus["note"]})
+			return
+		}
+		var body struct {
+			Client string `json:"client"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		client := strings.TrimSpace(body.Client)
+		if client == "all" {
+			client = ""
+		}
+		reconnected, missing := s.tunnelSupervisor.Reconnect(client)
+		if missing != "" {
+			writeJSON(w, 404, errBody("YOOOCLAW_TUNNEL_LABEL_NOT_FOUND", "隧道不存在："+missing))
+			return
+		}
+		writeJSON(w, 200, map[string]any{"ok": true, "mode": "relay", "reconnected": true, "labels": reconnected})
 	case "/tunnel/test":
-		// 回环自检：直接本地 ingest 一条 echo 通知。
-		_ = r
+		var body struct {
+			Client string `json:"client"`
+		}
+		if !decodeBody(w, r, &body) {
+			return
+		}
+		clientLabel := strings.TrimSpace(body.Client)
+		if clientLabel == "" || clientLabel == "all" {
+			clientLabel = "local"
+		}
 		res := s.storage.Ingest([]notif.RawNotification{{
 			ID: "echo_local_" + time.Now().Format("20060102150405"), App: "yoooclaw.selftest",
 			Title: "tunnel +test", Body: "echo", Timestamp: time.Now().Format(time.RFC3339),
-		}}, "local")
+		}}, clientLabel)
 		ok := res.Ingested > 0 || res.DedupedByID > 0 || res.DedupedByContent > 0
-		writeJSON(w, 200, map[string]any{"ok": ok, "mode": "standalone-http", "loopback": map[string]any{"ok": ok}})
+		writeJSON(w, 200, map[string]any{"ok": ok, "mode": s.relayStatusPayload()["mode"], "clientLabel": clientLabel, "loopback": map[string]any{"ok": ok}})
 	default:
 		writeJSON(w, 404, errBody("YOOOCLAW_NOT_FOUND", "未知路径："+path))
 	}
 }
 
+func filterRelayTunnels(value any, label string) any {
+	tunnels, ok := value.([]relay.TunnelStatus)
+	if !ok {
+		return value
+	}
+	out := make([]relay.TunnelStatus, 0, len(tunnels))
+	for _, tunnel := range tunnels {
+		if tunnel.Label == label {
+			out = append(out, tunnel)
+		}
+	}
+	return out
+}
+
 func decodeBody(w http.ResponseWriter, r *http.Request, out any) bool {
 	data, err := io.ReadAll(r.Body)
 	if err != nil {
diff --git a/internal/image/store.go b/internal/image/store.go
index 22f5939..a9716e5 100644
--- a/internal/image/store.go
+++ b/internal/image/store.go
@@ -4,10 +4,19 @@
 package image
 
 import (
+	"context"
 	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
 	"os"
 	"path/filepath"
 	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
 )
 
 // Metadata 是图片元数据。
@@ -34,6 +43,14 @@ type Entry struct {
 	SyncedAt    *string  `json:"syncedAt,omitempty"`
 }
 
+// Logger 是图片写侧依赖的最小日志接口。
+type Logger interface {
+	Info(string)
+	Warn(string)
+}
+
+var writeMu sync.Mutex
+
 // ReadIndex 读取 images/index.json 的 images[]；不存在返回空。
 func ReadIndex(imagesDir string) []Entry {
 	raw, err := os.ReadFile(filepath.Join(imagesDir, "index.json"))
@@ -49,6 +66,158 @@ func ReadIndex(imagesDir string) []Entry {
 	return wrapper.Images
 }
 
+func writeIndex(imagesDir string, entries []Entry) error {
+	return fsutil.WriteJSON(filepath.Join(imagesDir, "index.json"), struct {
+		Images []Entry `json:"images"`
+	}{Images: entries}, fsutil.ConfigFileMode)
+}
+
+func upsert(imagesDir string, entry Entry) error {
+	writeMu.Lock()
+	defer writeMu.Unlock()
+	entries := ReadIndex(imagesDir)
+	idx := -1
+	for i := range entries {
+		if entries[i].ImageID == entry.ImageID {
+			idx = i
+			break
+		}
+	}
+	if idx >= 0 {
+		entries[idx] = entry
+	} else {
+		entries = append(entries, entry)
+	}
+	if err := fsutil.EnsureDir(imagesDir, fsutil.DirMode); err != nil {
+		return err
+	}
+	return writeIndex(imagesDir, entries)
+}
+
+// SyncPayload 是 images.sync / POST /images 的请求体。
+type SyncPayload struct {
+	ImageID string   `json:"imageId"`
+	Image   Metadata `json:"image"`
+}
+
+// IngestResult 是图片同步即时返回。
+type IngestResult struct {
+	OK      bool   `json:"ok"`
+	ImageID string `json:"imageId"`
+	Status  string `json:"status"`
+	Deduped bool   `json:"deduped,omitempty"`
+}
+
+// Ingest 接收图片元数据，后台下载 OSS 文件。
+func Ingest(imagesDir string, payload SyncPayload, clientLabel string, maxBytes int64, logger Logger) (IngestResult, error) {
+	imageID := strings.TrimSpace(payload.ImageID)
+	if imageID == "" || strings.TrimSpace(payload.Image.OssImageURL) == "" || strings.TrimSpace(payload.Image.CreatedAt) == "" {
+		return IngestResult{}, fmt.Errorf("imageId / image.oss_image_url / image.created_at 必填")
+	}
+	if clientLabel == "" {
+		clientLabel = "default"
+	}
+	for _, existing := range ReadIndex(imagesDir) {
+		if existing.ImageID == imageID && existing.Metadata.OssImageURL == payload.Image.OssImageURL && existing.Status == "synced" {
+			return IngestResult{OK: true, ImageID: imageID, Status: "synced", Deduped: true}, nil
+		}
+	}
+	entry := Entry{
+		ImageID: imageID, ClientLabel: clientLabel, Metadata: payload.Image,
+		Status: "syncing", LastError: nil, SyncedAt: nil,
+	}
+	if err := upsert(imagesDir, entry); err != nil {
+		return IngestResult{}, err
+	}
+	go func() {
+		if err := downloadInBackground(imagesDir, entry, maxBytes, logger); err != nil {
+			logger.Warn("image[" + imageID + "] 后台下载异常：" + err.Error())
+		}
+	}()
+	return IngestResult{OK: true, ImageID: imageID, Status: "syncing"}, nil
+}
+
+func downloadInBackground(imagesDir string, entry Entry, maxBytes int64, logger Logger) error {
+	filesDir := filepath.Join(imagesDir, "files")
+	if err := fsutil.EnsureDir(filesDir, fsutil.DirMode); err != nil {
+		return err
+	}
+	if maxBytes <= 0 {
+		maxBytes = 20 * 1024 * 1024
+	}
+	relative := filepath.ToSlash(filepath.Join("files", entry.ImageID+"."+extFromMime(entry.Metadata.MimeType)))
+	dest := filepath.Join(imagesDir, relative)
+	err := downloadImage(entry.Metadata.OssImageURL, dest, maxBytes)
+	if err != nil {
+		msg := err.Error()
+		entry.Status = "sync_failed"
+		entry.LastError = &msg
+		entry.LocalFile = nil
+		_ = upsert(imagesDir, entry)
+		logger.Warn("image[" + entry.ImageID + "] 下载失败：" + msg)
+		return nil
+	}
+	entry.LocalFile = &relative
+	entry.Status = "synced"
+	entry.LastError = nil
+	now := time.Now().UTC().Format(time.RFC3339Nano)
+	entry.SyncedAt = &now
+	if err := upsert(imagesDir, entry); err != nil {
+		return err
+	}
+	logger.Info("image[" + entry.ImageID + "] 下载完成")
+	return nil
+}
+
+func downloadImage(rawURL, dest string, maxBytes int64) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+	if err != nil {
+		return err
+	}
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("OSS 返回 %d", resp.StatusCode)
+	}
+	if resp.ContentLength > 0 && resp.ContentLength > maxBytes {
+		return fmt.Errorf("图片超过上限 %d 字节", maxBytes)
+	}
+	f, err := os.OpenFile(dest, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	written, err := io.Copy(f, io.LimitReader(resp.Body, maxBytes+1))
+	if err != nil {
+		_ = os.Remove(dest)
+		return err
+	}
+	if written > maxBytes {
+		_ = os.Remove(dest)
+		return fmt.Errorf("图片超过上限 %d 字节", maxBytes)
+	}
+	return nil
+}
+
+func extFromMime(mime string) string {
+	mime = strings.ToLower(mime)
+	switch {
+	case strings.Contains(mime, "png"):
+		return "png"
+	case strings.Contains(mime, "webp"):
+		return "webp"
+	case strings.Contains(mime, "gif"):
+		return "gif"
+	default:
+		return "jpg"
+	}
+}
+
 // ResolveFile 把相对路径解析为绝对路径。
 func ResolveFile(imagesDir, relative string) string {
 	if filepath.IsAbs(relative) {
diff --git a/internal/image/store_test.go b/internal/image/store_test.go
new file mode 100644
index 0000000..2e7da9e
--- /dev/null
+++ b/internal/image/store_test.go
@@ -0,0 +1,78 @@
+package image
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+type testLogger struct{ t *testing.T }
+
+func (l testLogger) Info(msg string) { l.t.Log("[INFO] " + msg) }
+func (l testLogger) Warn(msg string) { l.t.Log("[WARN] " + msg) }
+
+func TestIngestDownloadsImage(t *testing.T) {
+	t.Parallel()
+	oss := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/img.png" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "image/png")
+		_, _ = w.Write([]byte("png-bytes"))
+	}))
+	defer oss.Close()
+
+	dir := filepath.Join(t.TempDir(), "images")
+	result, err := Ingest(dir, SyncPayload{
+		ImageID: "img_1",
+		Image: Metadata{
+			OssImageURL: oss.URL + "/img.png",
+			CreatedAt:   "2026-06-04T17:16:50+08:00",
+			MimeType:    "image/png",
+			SourceApp:   "camera",
+		},
+	}, "phone-a", 1024, testLogger{t})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.OK || result.Status != "syncing" {
+		t.Fatalf("unexpected ingest result: %+v", result)
+	}
+
+	waitFor(t, time.Second, func() bool {
+		entries := ReadIndex(dir)
+		return len(entries) == 1 && entries[0].Status == "synced" && entries[0].LocalFile != nil
+	})
+	entry := ReadIndex(dir)[0]
+	if entry.ClientLabel != "phone-a" {
+		t.Fatalf("client label mismatch: %q", entry.ClientLabel)
+	}
+	data, err := os.ReadFile(filepath.Join(dir, *entry.LocalFile))
+	if err != nil || string(data) != "png-bytes" {
+		t.Fatalf("image file mismatch: %q err=%v", string(data), err)
+	}
+
+	dedup, err := Ingest(dir, SyncPayload{ImageID: "img_1", Image: entry.Metadata}, "phone-a", 1024, testLogger{t})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !dedup.Deduped || dedup.Status != "synced" {
+		t.Fatalf("expected dedupe: %+v", dedup)
+	}
+}
+
+func waitFor(t *testing.T, timeout time.Duration, ok func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if ok() {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("condition not met before timeout")
+}
diff --git a/internal/recording/asr.go b/internal/recording/asr.go
new file mode 100644
index 0000000..e712e44
--- /dev/null
+++ b/internal/recording/asr.go
@@ -0,0 +1,641 @@
+package recording
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/creds"
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+const (
+	defaultLongRecordingPollInterval = 2 * time.Second
+	defaultLongRecordingMaxPolls     = 3600
+	defaultHTTPAttempts              = 3
+	defaultHTTPBackoff               = 2 * time.Second
+)
+
+var (
+	longRecordingRunningStatuses = map[string]bool{"PENDING": true, "RUNNING": true, "SUSPENDED": true}
+	longRecordingFailureStatuses = map[string]bool{"FAILED": true, "CANCELED": true, "UNKNOWN": true}
+	defaultEnvHosts              = map[string]string{
+		"development": "openclaw-service-dev.yoooclaw.com",
+		"test":        "openclaw-service-test.yoooclaw.com",
+		"production":  "openclaw-service.yoooclaw.com",
+	}
+	envSchemeRE        = regexp.MustCompile(`^(https?|wss?)://`)
+	envTrailingSlashRE = regexp.MustCompile(`/+$`)
+)
+
+// AsrConfig 是录音 ASR 配置。
+type AsrConfig struct {
+	Mode  string        `json:"mode"`
+	API   *AsrAPIConfig `json:"api,omitempty"`
+	Local any           `json:"local,omitempty"`
+}
+
+// AsrAPIConfig 是 model-proxy 长录音配置。
+type AsrAPIConfig struct {
+	Provider            string `json:"provider,omitempty"`
+	APIKey              string `json:"apiKey,omitempty"`
+	Endpoint            string `json:"endpoint,omitempty"`
+	Model               string `json:"model,omitempty"`
+	Language            string `json:"language,omitempty"`
+	EnableNormalization *bool  `json:"enableNormalization,omitempty"`
+	UserID              string `json:"userId,omitempty"`
+	DeviceID            string `json:"deviceId,omitempty"`
+	AppID               string `json:"appId,omitempty"`
+	RequestID           string `json:"requestId,omitempty"`
+	TraceParent         string `json:"traceParent,omitempty"`
+}
+
+// AsrInitResult 是 recordings.asr.init 返回。
+type AsrInitResult struct {
+	OK            bool   `json:"ok"`
+	Mode          string `json:"mode"`
+	Provider      string `json:"provider,omitempty"`
+	Endpoint      string `json:"endpoint,omitempty"`
+	Language      string `json:"language,omitempty"`
+	KeyConfigured bool   `json:"keyConfigured,omitempty"`
+	Error         string `json:"error,omitempty"`
+}
+
+// TranscriptionResult 是 ASR provider 结果。
+type TranscriptionResult struct {
+	OK          bool                `json:"ok"`
+	Text        string              `json:"text,omitempty"`
+	Segments    []TranscriptSegment `json:"segments,omitempty"`
+	Summary     string              `json:"summary,omitempty"`
+	SummaryText string              `json:"summaryText,omitempty"`
+	Category    string              `json:"category,omitempty"`
+	SourceInfo  TranscriptSource    `json:"sourceInfo,omitempty"`
+	RawResponse any                 `json:"rawResponse,omitempty"`
+	Error       string              `json:"error,omitempty"`
+}
+
+// ValidateAsrConfig 校验 ASR 配置。
+func ValidateAsrConfig(cfg *AsrConfig) string {
+	if cfg == nil || strings.TrimSpace(cfg.Mode) == "" {
+		return "asr.mode is required"
+	}
+	switch cfg.Mode {
+	case "api":
+		return ""
+	case "local":
+		return `本地 Whisper 模式已停用，请改用 asr.mode = "api"`
+	case "yoooclaw":
+		return "YoooClaw ASR 尚未实现（P2）"
+	default:
+		return "未知的 ASR mode: " + cfg.Mode
+	}
+}
+
+// IsAsrConfigured 判断 ASR 是否可用。
+func IsAsrConfigured(cfg *AsrConfig) bool {
+	return cfg != nil && ValidateAsrConfig(cfg) == ""
+}
+
+// LoadLocalAsrConfig 读取 recordings/asr-config.json。
+func LoadLocalAsrConfig(recordingsDir string) *AsrConfig {
+	var cfg AsrConfig
+	exists, err := fsutil.ReadJSON(filepath.Join(recordingsDir, "asr-config.json"), &cfg)
+	if err != nil || !exists {
+		return nil
+	}
+	return &cfg
+}
+
+// ResolveAsrConfig 优先使用 caller ASR，再回退本地配置；apiKey 为空时注入 account fallback。
+func ResolveAsrConfig(caller, local *AsrConfig, fallbackAPIKey string) *AsrConfig {
+	chosen := caller
+	if chosen == nil {
+		chosen = local
+	}
+	if chosen == nil || chosen.Mode != "api" {
+		return chosen
+	}
+	out := *chosen
+	api := AsrAPIConfig{}
+	if chosen.API != nil {
+		api = *chosen.API
+	}
+	if strings.TrimSpace(api.APIKey) == "" {
+		api.APIKey = strings.TrimSpace(fallbackAPIKey)
+	}
+	out.API = &api
+	return &out
+}
+
+// InitializeAsr 显式初始化/校验 ASR。
+func InitializeAsr(cfg *AsrConfig) AsrInitResult {
+	if errMsg := ValidateAsrConfig(cfg); errMsg != "" {
+		mode := ""
+		if cfg != nil {
+			mode = cfg.Mode
+		}
+		return AsrInitResult{OK: false, Mode: mode, Error: errMsg}
+	}
+	endpoint := resolveSubmitEndpoint(cfg.API)
+	keyConfigured := strings.TrimSpace(cfg.APIValue().APIKey) != "" || strings.TrimSpace(creds.ResolveAPIKey().Value) != ""
+	if !keyConfigured {
+		return AsrInitResult{
+			OK: false, Mode: "api", Provider: "model-proxy", Endpoint: endpoint,
+			Language: firstNonEmpty(cfg.APIValue().Language, "auto"), KeyConfigured: false,
+			Error: "API Key 未设置，请在本次 asr.api.apiKey 中传入，或先写入 credentials.json / 执行 yc auth set-api-key <apiKey>",
+		}
+	}
+	return AsrInitResult{
+		OK: true, Mode: "api", Provider: "model-proxy", Endpoint: endpoint,
+		Language: firstNonEmpty(cfg.APIValue().Language, "auto"), KeyConfigured: true,
+	}
+}
+
+// APIValue 返回非 nil API 配置副本。
+func (c *AsrConfig) APIValue() AsrAPIConfig {
+	if c == nil || c.API == nil {
+		return AsrAPIConfig{}
+	}
+	return *c.API
+}
+
+// TranscribeAudio 执行 ASR 转写。
+func TranscribeAudio(audioFilePath string, cfg AsrConfig, logger Logger, audioOssURL string, audioDurationMS float64) TranscriptionResult {
+	if _, err := os.Stat(audioFilePath); err != nil {
+		return TranscriptionResult{OK: false, Error: "音频文件不存在: " + audioFilePath}
+	}
+	logger.Info("[asr] 开始转写: mode=" + cfg.Mode + ", file=" + audioFilePath)
+	switch cfg.Mode {
+	case "api":
+		return transcribeWithModelProxy(audioOssURL, audioDurationMS, cfg.API, logger)
+	case "local":
+		return TranscriptionResult{OK: false, Error: `本地 Whisper 模式已停用，请改用 asr.mode = "api"`}
+	case "yoooclaw":
+		return TranscriptionResult{OK: false, Error: "YoooClaw ASR 尚未实现（P2）"}
+	default:
+		return TranscriptionResult{OK: false, Error: "未知的 ASR mode: " + cfg.Mode}
+	}
+}
+
+// WorkflowResult 是完整 ASR 工作流落盘结果。
+type WorkflowResult struct {
+	OK                     bool             `json:"ok"`
+	TranscriptFilename     string           `json:"transcriptFilename,omitempty"`
+	TranscriptDataFilename string           `json:"transcriptDataFilename,omitempty"`
+	SummaryFilename        string           `json:"summaryFilename,omitempty"`
+	Transcript             []TranscriptItem `json:"transcript,omitempty"`
+	Summary                string           `json:"summary,omitempty"`
+	Title                  string           `json:"title,omitempty"`
+	Error                  string           `json:"error,omitempty"`
+}
+
+// RunTranscriptionWorkflow 转写并写 transcript-data/transcripts/summaries。
+func RunTranscriptionWorkflow(storage *Storage, entry Entry, cfg AsrConfig, logger Logger) WorkflowResult {
+	audioPath := storage.AudioFilePath(entry.ID, entry.Metadata.OssAudioURL)
+	durationMS := entry.Metadata.DurationSec * 1000
+	result := TranscribeAudio(audioPath, cfg, logger, entry.Metadata.OssAudioURL, durationMS)
+	if !result.OK {
+		return WorkflowResult{OK: false, Error: result.Error}
+	}
+
+	title := strings.TrimSpace(result.Summary)
+	if title == "" {
+		title = extractSummary(result.Text)
+	}
+	summary := result.SummaryText
+	result.Summary = title
+	source := result.SourceInfo
+	if source.Provider == "" {
+		source.Provider = cfg.Mode
+		if cfg.Mode == "api" {
+			source.Provider = "model-proxy"
+		}
+	}
+	doc := BuildTranscriptDocument(entry.ID, source, title, result.Category, summary, result.Text, result.Segments, result.RawResponse)
+	docBytes, _ := json.MarshalIndent(doc, "", "  ")
+
+	transcriptDataFilename := TranscriptDataFilename(entry.ID)
+	if err := fsutil.WriteAtomic(filepath.Join(storage.TranscriptDataDir(), transcriptDataFilename), append(docBytes, '\n'), fsutil.ConfigFileMode); err != nil {
+		return WorkflowResult{OK: false, Error: err.Error()}
+	}
+	logger.Info("[asr] 转写 JSON 已写入: " + filepath.Join(storage.TranscriptDataDir(), transcriptDataFilename))
+
+	markdown := BuildTranscriptMarkdown(result, entry.Metadata.Markers, entry.Metadata.Name, entry.Metadata.DurationSec, entry.Metadata.CreatedAt)
+	transcriptFilename := TranscriptFilename(entry.ID, title)
+	if err := fsutil.WriteAtomic(filepath.Join(storage.TranscriptsDir(), transcriptFilename), []byte(markdown), fsutil.ConfigFileMode); err != nil {
+		return WorkflowResult{OK: false, Error: err.Error()}
+	}
+	logger.Info("[asr] 转写文本已写入: " + filepath.Join(storage.TranscriptsDir(), transcriptFilename))
+
+	summaryFilename := ""
+	if strings.TrimSpace(summary) != "" {
+		summaryFilename = SummaryFilename(entry.ID)
+		if err := fsutil.WriteAtomic(filepath.Join(storage.SummariesDir(), summaryFilename), []byte(strings.TrimSpace(summary)), fsutil.ConfigFileMode); err != nil {
+			return WorkflowResult{OK: false, Error: err.Error()}
+		}
+		logger.Info("[asr] 摘要文本已写入: " + filepath.Join(storage.SummariesDir(), summaryFilename))
+	}
+
+	return WorkflowResult{
+		OK: true, TranscriptFilename: transcriptFilename, TranscriptDataFilename: transcriptDataFilename,
+		SummaryFilename: summaryFilename, Transcript: ExtractSourceTextListFromDocument(doc),
+		Summary: summary, Title: title,
+	}
+}
+
+type submitRequest struct {
+	AudioOssURL         string `json:"audioOssUrl"`
+	Language            string `json:"language,omitempty"`
+	EnableNormalization *bool  `json:"enableNormalization,omitempty"`
+}
+
+type statusResponse struct {
+	TaskID       string        `json:"taskId,omitempty"`
+	Status       string        `json:"status,omitempty"`
+	RequestID    string        `json:"requestId,omitempty"`
+	ErrorMessage string        `json:"errorMessage,omitempty"`
+	RecordResult *recordResult `json:"recordResult,omitempty"`
+}
+
+type recordResult struct {
+	SourceText     string           `json:"sourceText,omitempty"`
+	SourceTextList []sourceTextItem `json:"sourceTextList,omitempty"`
+	SummaryResult  string           `json:"summaryResult,omitempty"`
+	Category       string           `json:"category,omitempty"`
+	Title          string           `json:"title,omitempty"`
+}
+
+type sourceTextItem struct {
+	Content   string   `json:"content,omitempty"`
+	SpeakerID *int     `json:"speakerId,omitempty"`
+	StartTime *float64 `json:"startTime,omitempty"`
+	EndTime   *float64 `json:"endTime,omitempty"`
+}
+
+type responseEnvelope struct {
+	Success *bool           `json:"success,omitempty"`
+	Code    any             `json:"code,omitempty"`
+	Message string          `json:"message,omitempty"`
+	Data    json.RawMessage `json:"data,omitempty"`
+}
+
+func transcribeWithModelProxy(audioOssURL string, audioDurationMS float64, apiConfig *AsrAPIConfig, logger Logger) TranscriptionResult {
+	audioOssURL = strings.TrimSpace(audioOssURL)
+	if audioOssURL == "" {
+		return TranscriptionResult{OK: false, Error: "API 模式缺少 audioOssUrl，无法调用 model-proxy"}
+	}
+	api := AsrAPIConfig{}
+	if apiConfig != nil {
+		api = *apiConfig
+	}
+	apiKey := normalizeAPIKeyHeader(api.APIKey)
+	if apiKey == "" {
+		apiKey = normalizeAPIKeyHeader(creds.ResolveAPIKey().Value)
+	}
+	if apiKey == "" {
+		return TranscriptionResult{OK: false, Error: "API Key 未设置，无法调用 model-proxy"}
+	}
+	submitEndpoint := resolveSubmitEndpoint(&api)
+	body := submitRequest{AudioOssURL: audioOssURL}
+	if strings.TrimSpace(api.Language) != "" {
+		body.Language = strings.TrimSpace(api.Language)
+	}
+	if api.EnableNormalization != nil {
+		body.EnableNormalization = api.EnableNormalization
+	}
+	logger.Info("[asr-submit] 提交长录音任务: endpoint=" + submitEndpoint)
+
+	raw, status, err := doJSONWithRetry(http.MethodPost, submitEndpoint, apiKey, body, logger, "asr-submit")
+	if err != nil {
+		return TranscriptionResult{OK: false, Error: "Model Proxy ASR submit network error: " + err.Error()}
+	}
+	if status < 200 || status >= 300 {
+		return TranscriptionResult{OK: false, Error: fmt.Sprintf("Model Proxy ASR error: %d %s", status, truncate(string(raw), 200))}
+	}
+	data, envelopeErr := unwrapStatusResponse(raw)
+	if envelopeErr != "" {
+		return TranscriptionResult{OK: false, Error: "Model Proxy ASR 提交失败: " + envelopeErr}
+	}
+	taskID := strings.TrimSpace(data.TaskID)
+	requestID := strings.TrimSpace(data.RequestID)
+	taskStatus := normalizeTaskStatus(data.Status)
+	if taskID == "" {
+		return TranscriptionResult{OK: false, Error: "Model Proxy ASR 响应缺少 taskId"}
+	}
+	logger.Info(fmt.Sprintf("[asr] Model Proxy 长录音任务已提交: taskId=%s, status=%s, requestId=%s", taskID, firstNonEmpty(taskStatus, "UNKNOWN"), firstNonEmpty(requestID, "n/a")))
+	if longRecordingFailureStatuses[taskStatus] {
+		return TranscriptionResult{OK: false, Error: buildStatusError(data, taskStatus)}
+	}
+	return pollLongRecordingTask(apiKey, taskID, requestID, audioDurationMS, &api, logger)
+}
+
+func pollLongRecordingTask(apiKey, taskID, initialRequestID string, audioDurationMS float64, apiConfig *AsrAPIConfig, logger Logger) TranscriptionResult {
+	base := resolveQueryBaseURL(apiConfig)
+	pollInterval := pollInterval()
+	lastStatus := ""
+	for attempt := 1; attempt <= defaultLongRecordingMaxPolls; attempt++ {
+		queryURL := strings.TrimRight(base, "/") + "/" + urlPathEscape(taskID)
+		raw, statusCode, err := doJSONGet(queryURL, apiKey)
+		if err != nil {
+			logger.Warn(fmt.Sprintf("[asr-query] 长录音任务查询网络异常: taskId=%s, attempt=%d, error=%s", taskID, attempt, err.Error()))
+			if attempt < defaultLongRecordingMaxPolls {
+				time.Sleep(pollInterval)
+				continue
+			}
+			return TranscriptionResult{OK: false, Error: "Model Proxy ASR query network error: " + err.Error()}
+		}
+		if statusCode < 200 || statusCode >= 300 {
+			if isRetryableStatus(statusCode) && attempt < defaultLongRecordingMaxPolls {
+				logger.Warn(fmt.Sprintf("[asr-query] 长录音任务查询暂时失败: taskId=%s, attempt=%d, status=%d", taskID, attempt, statusCode))
+				time.Sleep(pollInterval)
+				continue
+			}
+			return TranscriptionResult{OK: false, Error: fmt.Sprintf("Model Proxy ASR query error: %d %s", statusCode, truncate(string(raw), 200))}
+		}
+		data, envelopeErr := unwrapStatusResponse(raw)
+		if envelopeErr != "" {
+			return TranscriptionResult{OK: false, Error: "Model Proxy ASR 查询失败: " + envelopeErr}
+		}
+		status := firstNonEmpty(normalizeTaskStatus(data.Status), "UNKNOWN")
+		requestID := firstNonEmpty(strings.TrimSpace(data.RequestID), initialRequestID)
+		if status != lastStatus {
+			logger.Info(fmt.Sprintf("[asr] Model Proxy 长录音任务状态: taskId=%s, status=%s, attempt=%d, requestId=%s", taskID, status, attempt, firstNonEmpty(requestID, "n/a")))
+			lastStatus = status
+		}
+		if status == "SUCCEEDED" {
+			return buildSuccessResult(taskID, requestID, data, audioDurationMS, logger)
+		}
+		if longRecordingFailureStatuses[status] {
+			return TranscriptionResult{OK: false, Error: buildStatusError(data, status)}
+		}
+		if !longRecordingRunningStatuses[status] {
+			return TranscriptionResult{OK: false, Error: "Model Proxy ASR 返回未知任务状态: " + status}
+		}
+		if attempt < defaultLongRecordingMaxPolls {
+			time.Sleep(pollInterval)
+		}
+	}
+	return TranscriptionResult{OK: false, Error: fmt.Sprintf("Model Proxy ASR 轮询超时: taskId=%s", taskID)}
+}
+
+func buildSuccessResult(taskID, requestID string, data statusResponse, audioDurationMS float64, logger Logger) TranscriptionResult {
+	text, segments := extractTextAndSegments(data.RecordResult, audioDurationMS)
+	sourceText := ""
+	summaryText := ""
+	title := ""
+	category := ""
+	if data.RecordResult != nil {
+		sourceText = strings.TrimSpace(data.RecordResult.SourceText)
+		summaryText = strings.TrimSpace(data.RecordResult.SummaryResult)
+		title = strings.TrimSpace(data.RecordResult.Title)
+		category = strings.TrimSpace(data.RecordResult.Category)
+	}
+	if text == "" {
+		text = firstNonEmpty(sourceText, summaryText)
+		if sourceText == "" && summaryText != "" {
+			logger.Warn("[asr] Model Proxy 长录音结果缺少 sourceTextList/sourceText，已回退使用 summaryResult 作为转写文本: taskId=" + taskID)
+		}
+	}
+	logger.Info(fmt.Sprintf("[asr] Model Proxy 长录音转写完成: taskId=%s, requestId=%s, chars=%d", taskID, firstNonEmpty(requestID, "n/a"), len([]rune(text))))
+	return TranscriptionResult{
+		OK: true, Text: text, Segments: segments, Summary: title, SummaryText: summaryText, Category: category,
+		SourceInfo:  TranscriptSource{Provider: "model-proxy", TaskID: taskID, RequestID: requestID, Status: "SUCCEEDED"},
+		RawResponse: data,
+	}
+}
+
+func extractTextAndSegments(result *recordResult, finalFallbackEndMS float64) (string, []TranscriptSegment) {
+	if result == nil || len(result.SourceTextList) == 0 {
+		return "", nil
+	}
+	segments := make([]TranscriptSegment, 0, len(result.SourceTextList))
+	parts := make([]string, 0, len(result.SourceTextList))
+	for i, item := range result.SourceTextList {
+		content := strings.TrimSpace(item.Content)
+		if content == "" {
+			continue
+		}
+		start := float64(0)
+		if item.StartTime != nil {
+			start = *item.StartTime
+		}
+		end := start
+		if item.EndTime != nil {
+			end = *item.EndTime
+		} else if i+1 < len(result.SourceTextList) && result.SourceTextList[i+1].StartTime != nil {
+			end = *result.SourceTextList[i+1].StartTime
+		} else if finalFallbackEndMS >= 0 {
+			end = finalFallbackEndMS
+		}
+		if end < start {
+			end = start
+		}
+		segments = append(segments, TranscriptSegment{
+			Text: content, StartMS: &start, EndMS: &end, SpeakerID: item.SpeakerID,
+		})
+		parts = append(parts, content)
+	}
+	return strings.Join(parts, "\n\n"), segments
+}
+
+func doJSONWithRetry(method, endpoint, apiKey string, body any, logger Logger, contextName string) ([]byte, int, error) {
+	payload, _ := json.Marshal(body)
+	var lastErr error
+	var lastRaw []byte
+	var lastStatus int
+	for attempt := 1; attempt <= defaultHTTPAttempts; attempt++ {
+		reqCtx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+		req, err := http.NewRequestWithContext(reqCtx, method, endpoint, bytes.NewReader(payload))
+		if err != nil {
+			cancel()
+			return nil, 0, err
+		}
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("X-Api-Key-Id", apiKey)
+		resp, err := http.DefaultClient.Do(req)
+		if err == nil && resp != nil {
+			lastStatus = resp.StatusCode
+			lastRaw, err = io.ReadAll(resp.Body)
+			_ = resp.Body.Close()
+		}
+		cancel()
+		if err == nil && !isRetryableStatus(lastStatus) {
+			return lastRaw, lastStatus, nil
+		}
+		if err != nil {
+			lastErr = err
+		}
+		if attempt < defaultHTTPAttempts {
+			logger.Warn(fmt.Sprintf("[%s] request retry %d/%d", contextName, attempt, defaultHTTPAttempts))
+			time.Sleep(defaultHTTPBackoff * time.Duration(1<<(attempt-1)))
+		}
+	}
+	if lastErr != nil {
+		return lastRaw, lastStatus, lastErr
+	}
+	return lastRaw, lastStatus, nil
+}
+
+func doJSONGet(endpoint, apiKey string) ([]byte, int, error) {
+	reqCtx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, endpoint, nil)
+	if err != nil {
+		return nil, 0, err
+	}
+	req.Header.Set("X-Api-Key-Id", apiKey)
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(resp.Body)
+	return raw, resp.StatusCode, err
+}
+
+func unwrapStatusResponse(raw []byte) (statusResponse, string) {
+	var direct statusResponse
+	_ = json.Unmarshal(raw, &direct)
+	var envelope responseEnvelope
+	if json.Unmarshal(raw, &envelope) != nil || len(envelope.Data) == 0 {
+		return direct, ""
+	}
+	explicitFailure := envelope.Success != nil && !*envelope.Success
+	message := strings.TrimSpace(envelope.Message)
+	if !explicitFailure && (message == "" || string(envelope.Data) != "null") {
+		var data statusResponse
+		if json.Unmarshal(envelope.Data, &data) == nil {
+			return data, ""
+		}
+	}
+	code := normalizeCode(envelope.Code)
+	if code != "" && message != "" {
+		return statusResponse{}, code + " " + message
+	}
+	if message != "" {
+		return statusResponse{}, message
+	}
+	if code != "" {
+		return statusResponse{}, code
+	}
+	return statusResponse{}, "response envelope indicates failure"
+}
+
+func normalizeCode(v any) string {
+	switch t := v.(type) {
+	case string:
+		return strings.TrimSpace(t)
+	case float64:
+		return fmt.Sprintf("%.0f", t)
+	default:
+		return ""
+	}
+}
+
+func buildStatusError(data statusResponse, status string) string {
+	if strings.TrimSpace(data.ErrorMessage) != "" {
+		return "Model Proxy ASR " + status + ": " + strings.TrimSpace(data.ErrorMessage)
+	}
+	return "Model Proxy ASR " + status
+}
+
+func resolveSubmitEndpoint(apiConfig *AsrAPIConfig) string {
+	if apiConfig != nil && strings.TrimSpace(apiConfig.Endpoint) != "" {
+		return strings.TrimSpace(apiConfig.Endpoint)
+	}
+	return "https://" + envHost() + "/api/model-proxy/long-recording/submit-task"
+}
+
+func resolveQueryBaseURL(apiConfig *AsrAPIConfig) string {
+	if apiConfig != nil && strings.TrimSpace(apiConfig.Endpoint) != "" {
+		endpoint := strings.TrimRight(strings.TrimSpace(apiConfig.Endpoint), "/")
+		if strings.HasSuffix(endpoint, "/submit-task") {
+			return strings.TrimSuffix(endpoint, "/submit-task") + "/query-task-result"
+		}
+		return endpoint
+	}
+	return "https://" + envHost() + "/api/model-proxy/long-recording/query-task-result"
+}
+
+func envHost() string {
+	env := strings.TrimSpace(os.Getenv("PHONE_NOTIFICATIONS_ENV"))
+	if env != "development" && env != "test" && env != "production" {
+		env = "production"
+	}
+	var override string
+	switch env {
+	case "development":
+		override = os.Getenv("OPENCLAW_HOST_DEVELOPMENT")
+	case "test":
+		override = os.Getenv("OPENCLAW_HOST_TEST")
+	case "production":
+		override = os.Getenv("OPENCLAW_HOST_PRODUCTION")
+	}
+	if h := normalizeEnvHost(override); h != "" {
+		return h
+	}
+	return defaultEnvHosts[env]
+}
+
+func normalizeEnvHost(host string) string {
+	trimmed := strings.TrimSpace(host)
+	if trimmed == "" {
+		return ""
+	}
+	trimmed = envSchemeRE.ReplaceAllString(trimmed, "")
+	return envTrailingSlashRE.ReplaceAllString(trimmed, "")
+}
+
+func normalizeAPIKeyHeader(apiKey string) string {
+	apiKey = strings.TrimSpace(apiKey)
+	return strings.TrimPrefix(apiKey, "Bearer ")
+}
+
+func normalizeTaskStatus(status string) string {
+	return strings.ToUpper(strings.TrimSpace(status))
+}
+
+func pollInterval() time.Duration {
+	raw := strings.TrimSpace(os.Getenv("OPENCLAW_ASR_POLL_INTERVAL_MS"))
+	if raw == "" {
+		return defaultLongRecordingPollInterval
+	}
+	var ms int64
+	if _, err := fmt.Sscanf(raw, "%d", &ms); err == nil && ms >= 0 {
+		return time.Duration(ms) * time.Millisecond
+	}
+	return defaultLongRecordingPollInterval
+}
+
+func isRetryableStatus(status int) bool {
+	return status == 429 || status >= 500
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max]
+}
+
+func urlPathEscape(s string) string {
+	r := strings.NewReplacer(" ", "%20", "/", "%2F", "?", "%3F", "#", "%23")
+	return r.Replace(s)
+}
diff --git a/internal/recording/downloader.go b/internal/recording/downloader.go
new file mode 100644
index 0000000..6119e99
--- /dev/null
+++ b/internal/recording/downloader.go
@@ -0,0 +1,133 @@
+package recording
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+const (
+	defaultDownloadTimeout = 5 * time.Minute
+	defaultDownloadRetries = 3
+	defaultRetryBackoff    = 2 * time.Second
+)
+
+// DownloadOptions 控制 OSS 下载重试与超时。
+type DownloadOptions struct {
+	Timeout      time.Duration
+	MaxRetries   int
+	RetryBackoff time.Duration
+	Client       *http.Client
+}
+
+// DownloadResult 是单个文件下载结果。
+type DownloadResult struct {
+	OK        bool          `json:"ok"`
+	SizeBytes int64         `json:"sizeBytes,omitempty"`
+	Elapsed   time.Duration `json:"-"`
+	Error     string        `json:"error,omitempty"`
+}
+
+// RecordingDownloadResult 是录音音频 + SRT 的下载结果。
+type RecordingDownloadResult struct {
+	Audio DownloadResult  `json:"audio"`
+	SRT   *DownloadResult `json:"srt,omitempty"`
+}
+
+// DownloadFile 从 URL 下载文件到 destPath。
+func DownloadFile(rawURL, destPath string, logger Logger, opts DownloadOptions) DownloadResult {
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = defaultDownloadTimeout
+	}
+	retries := opts.MaxRetries
+	if retries <= 0 {
+		retries = defaultDownloadRetries
+	}
+	backoff := opts.RetryBackoff
+	if backoff <= 0 {
+		backoff = defaultRetryBackoff
+	}
+	client := opts.Client
+	if client == nil {
+		client = http.DefaultClient
+	}
+
+	_ = fsutil.EnsureDir(filepath.Dir(destPath), fsutil.DirMode)
+	var lastErr string
+	for attempt := 1; attempt <= retries; attempt++ {
+		start := time.Now()
+		logger.Info(fmt.Sprintf("[downloader] 开始下载 (attempt %d/%d): %s", attempt, retries, rawURL))
+		ctx, cancel := context.WithTimeout(context.Background(), timeout)
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+		if err != nil {
+			cancel()
+			return DownloadResult{OK: false, Error: err.Error()}
+		}
+		resp, err := client.Do(req)
+		if err == nil && resp != nil {
+			err = writeDownloadResponse(resp, destPath)
+		}
+		if resp != nil && resp.Body != nil {
+			_ = resp.Body.Close()
+		}
+		cancel()
+
+		if err == nil {
+			info, statErr := os.Stat(destPath)
+			size := int64(0)
+			if statErr == nil {
+				size = info.Size()
+			}
+			elapsed := time.Since(start)
+			logger.Info(fmt.Sprintf("[downloader] 下载完成: %s (%d bytes, %s)", destPath, size, elapsed))
+			return DownloadResult{OK: true, SizeBytes: size, Elapsed: elapsed}
+		}
+
+		lastErr = err.Error()
+		_ = os.Remove(destPath)
+		logger.Warn(fmt.Sprintf("[downloader] 下载失败 (attempt %d/%d): %s", attempt, retries, lastErr))
+		if attempt < retries {
+			time.Sleep(backoff * time.Duration(1<<(attempt-1)))
+		}
+	}
+	return DownloadResult{OK: false, Error: lastErr}
+}
+
+func writeDownloadResponse(resp *http.Response, destPath string) error {
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("HTTP %d %s", resp.StatusCode, resp.Status)
+	}
+	if resp.Body == nil {
+		return fmt.Errorf("响应体为空")
+	}
+	f, err := os.OpenFile(destPath, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	if _, err := io.Copy(f, resp.Body); err != nil {
+		_ = f.Close()
+		return err
+	}
+	return f.Close()
+}
+
+// DownloadRecordingFiles 下载录音音频与可选 SRT。
+func DownloadRecordingFiles(audioURL, srtURL, audioDestPath, srtDestPath string, logger Logger, opts DownloadOptions) RecordingDownloadResult {
+	audio := DownloadFile(audioURL, audioDestPath, logger, opts)
+	var srt *DownloadResult
+	if srtURL != "" {
+		res := DownloadFile(srtURL, srtDestPath, logger, opts)
+		if !res.OK {
+			logger.Warn("[downloader] 打点文件下载失败（非致命）: " + res.Error)
+		}
+		srt = &res
+	}
+	return RecordingDownloadResult{Audio: audio, SRT: srt}
+}
diff --git a/internal/recording/events.go b/internal/recording/events.go
new file mode 100644
index 0000000..5b3e92a
--- /dev/null
+++ b/internal/recording/events.go
@@ -0,0 +1,54 @@
+package recording
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+// StatusEvent 是录音状态变化事件。
+type StatusEvent struct {
+	RecordingID        string           `json:"recordingId"`
+	TransferStatus     string           `json:"transfer_status"`
+	AudioFile          string           `json:"audioFile,omitempty"`
+	SrtFile            string           `json:"srtFile,omitempty"`
+	TranscriptDataFile string           `json:"transcriptDataFile,omitempty"`
+	TranscriptFile     string           `json:"transcriptFile,omitempty"`
+	Transcript         []TranscriptItem `json:"transcript,omitempty"`
+	Summary            string           `json:"summary,omitempty"`
+	Title              string           `json:"title"`
+	UpdatedAt          string           `json:"updatedAt"`
+	Error              string           `json:"error,omitempty"`
+}
+
+// EventLog 是 recordings/state/events.jsonl append-only 日志。
+type EventLog struct {
+	Path string
+}
+
+// NewEventLog 构造事件日志。
+func NewEventLog(recordingsDir string) *EventLog {
+	path := filepath.Join(recordingsDir, "state", "events.jsonl")
+	_ = fsutil.EnsureDir(filepath.Dir(path), fsutil.DirMode)
+	return &EventLog{Path: path}
+}
+
+// Append 追加一条状态事件。
+func (l *EventLog) Append(event StatusEvent) error {
+	record := map[string]any{"ts": nowISO()}
+	data, _ := json.Marshal(event)
+	_ = json.Unmarshal(data, &record)
+	line, err := json.Marshal(record)
+	if err != nil {
+		return err
+	}
+	f, err := os.OpenFile(l.Path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	_, err = f.Write(append(line, '\n'))
+	return err
+}
diff --git a/internal/recording/handler.go b/internal/recording/handler.go
new file mode 100644
index 0000000..f6cafcb
--- /dev/null
+++ b/internal/recording/handler.go
@@ -0,0 +1,224 @@
+package recording
+
+import "fmt"
+
+// SyncResult 是 recordings.sync 的即时返回。
+type SyncResult struct {
+	OK             bool   `json:"ok"`
+	RecordingID    string `json:"recordingId"`
+	TransferStatus string `json:"transfer_status"`
+	Error          string `json:"error,omitempty"`
+}
+
+// SyncOptions 控制 sync 后台流程。
+type SyncOptions struct {
+	NotifyStatus    func(StatusEvent)
+	DownloadOptions DownloadOptions
+}
+
+// HandleRecordingSync 处理 recordings.sync：元数据入库后后台下载 OSS，并按配置触发 ASR。
+func HandleRecordingSync(recordingID string, metadata Metadata, storage *Storage, asr *AsrConfig, logger Logger, opts SyncOptions) SyncResult {
+	existing, found := storage.FindByID(recordingID)
+	shouldDownloadAndSync := !found ||
+		existing.Metadata.OssAudioURL != metadata.OssAudioURL ||
+		existing.AudioFile == "" ||
+		existing.Status == StatusSyncingOpenClaw ||
+		existing.Status == StatusSyncFailed
+
+	if _, err := storage.Ingest(recordingID, metadata, ""); err != nil {
+		return SyncResult{OK: false, RecordingID: recordingID, TransferStatus: StatusSyncFailed, Error: err.Error()}
+	}
+	if shouldDownloadAndSync {
+		go func() {
+			if err := runRecordingSyncInBackground(metadata, recordingID, storage, asr, logger, opts); err != nil {
+				message := "录音同步失败: " + err.Error()
+				logger.Error("[recording-sync] " + message + ": " + recordingID)
+				if current, ok := storage.FindByID(recordingID); ok && current.Status == StatusSyncingOpenClaw {
+					_, _ = storage.UpdateStatus(recordingID, StatusSyncFailed)
+				}
+				_ = storage.SetLastError(recordingID, message)
+				emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, message, nil)
+			}
+		}()
+	} else {
+		logger.Info("[recording-sync] 录音已存在且音频未变化，跳过重复下载: " + recordingID)
+		emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, "", nil)
+		if current, ok := storage.FindByID(recordingID); ok && current.Status == StatusSynced && IsAsrConfigured(asr) {
+			go func() {
+				if err := TriggerTranscription(recordingID, storage, *asr, logger, opts); err != nil {
+					logger.Error("[asr-trigger] 转写触发失败: " + recordingID + ", " + err.Error())
+				}
+			}()
+		}
+	}
+
+	current, ok := storage.FindByID(recordingID)
+	status := StatusSyncingOpenClaw
+	lastErr := ""
+	if ok {
+		status = current.Status
+		lastErr = current.LastError
+	}
+	return SyncResult{OK: true, RecordingID: recordingID, TransferStatus: status, Error: lastErr}
+}
+
+// HandleRecordingSyncWithClientLabel 与 HandleRecordingSync 相同，但显式写入 clientLabel。
+func HandleRecordingSyncWithClientLabel(recordingID string, metadata Metadata, clientLabel string, storage *Storage, asr *AsrConfig, logger Logger, opts SyncOptions) SyncResult {
+	existing, found := storage.FindByID(recordingID)
+	shouldDownloadAndSync := !found ||
+		existing.Metadata.OssAudioURL != metadata.OssAudioURL ||
+		existing.AudioFile == "" ||
+		existing.Status == StatusSyncingOpenClaw ||
+		existing.Status == StatusSyncFailed
+	if _, err := storage.Ingest(recordingID, metadata, clientLabel); err != nil {
+		return SyncResult{OK: false, RecordingID: recordingID, TransferStatus: StatusSyncFailed, Error: err.Error()}
+	}
+	if shouldDownloadAndSync {
+		go func() {
+			if err := runRecordingSyncInBackground(metadata, recordingID, storage, asr, logger, opts); err != nil {
+				message := "录音同步失败: " + err.Error()
+				logger.Error("[recording-sync] " + message + ": " + recordingID)
+				if current, ok := storage.FindByID(recordingID); ok && current.Status == StatusSyncingOpenClaw {
+					_, _ = storage.UpdateStatus(recordingID, StatusSyncFailed)
+				}
+				_ = storage.SetLastError(recordingID, message)
+				emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, message, nil)
+			}
+		}()
+	} else {
+		logger.Info("[recording-sync] 录音已存在且音频未变化，跳过重复下载: " + recordingID)
+		emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, "", nil)
+		if current, ok := storage.FindByID(recordingID); ok && current.Status == StatusSynced && IsAsrConfigured(asr) {
+			go func() {
+				if err := TriggerTranscription(recordingID, storage, *asr, logger, opts); err != nil {
+					logger.Error("[asr-trigger] 转写触发失败: " + recordingID + ", " + err.Error())
+				}
+			}()
+		}
+	}
+	current, ok := storage.FindByID(recordingID)
+	status := StatusSyncingOpenClaw
+	lastErr := ""
+	if ok {
+		status = current.Status
+		lastErr = current.LastError
+	}
+	return SyncResult{OK: true, RecordingID: recordingID, TransferStatus: status, Error: lastErr}
+}
+
+func runRecordingSyncInBackground(metadata Metadata, recordingID string, storage *Storage, asr *AsrConfig, logger Logger, opts SyncOptions) error {
+	audioDestPath := storage.AudioFilePath(recordingID, metadata.OssAudioURL)
+	srtDestPath := storage.SrtFilePath(recordingID)
+	logger.Info(fmt.Sprintf("[recording-sync] 开始下载录音文件: %s, audio=%s", recordingID, metadata.OssAudioURL))
+	download := DownloadRecordingFiles(metadata.OssAudioURL, metadata.OssSrtURL, audioDestPath, srtDestPath, logger, opts.DownloadOptions)
+	if !download.Audio.OK {
+		message := "音频下载失败: " + download.Audio.Error
+		logger.Error("[recording-sync] " + message + ": " + recordingID)
+		_, _ = storage.UpdateStatus(recordingID, StatusSyncFailed)
+		_ = storage.SetLastError(recordingID, message)
+		emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, message, nil)
+		return nil
+	}
+	_ = storage.SetLastError(recordingID, "")
+	_ = storage.SetAudioFile(recordingID, AudioFilename(recordingID, metadata.OssAudioURL))
+	if download.SRT != nil && download.SRT.OK {
+		_ = storage.SetSrtFile(recordingID, SrtFilename(recordingID))
+	}
+	_, _ = storage.UpdateStatus(recordingID, StatusSynced)
+	logger.Info("[recording-sync] 录音已同步: " + recordingID)
+	emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, "", nil)
+
+	if IsAsrConfigured(asr) && CanStartTranscription(StatusSynced) {
+		return TriggerTranscription(recordingID, storage, *asr, logger, opts)
+	}
+	return nil
+}
+
+// TriggerTranscription 触发 ASR 转写。
+func TriggerTranscription(recordingID string, storage *Storage, asr AsrConfig, logger Logger, opts SyncOptions) error {
+	entry, ok := storage.FindByID(recordingID)
+	if !ok {
+		logger.Warn("[asr-trigger] 录音不存在: " + recordingID)
+		return nil
+	}
+	if !CanStartTranscription(entry.Status) {
+		logger.Warn("[asr-trigger] 当前状态不允许转写: " + recordingID + " (status=" + entry.Status + ")")
+		return nil
+	}
+	if _, err := storage.UpdateStatus(recordingID, StatusTranscribing); err != nil {
+		return err
+	}
+	_ = storage.SetLastError(recordingID, "")
+	emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, "", nil)
+
+	entry, _ = storage.FindByID(recordingID)
+	result := RunTranscriptionWorkflow(storage, entry, asr, logger)
+	if !result.OK {
+		message := "转写失败: " + result.Error
+		logger.Error("[asr-trigger] " + message + ": " + recordingID)
+		_, _ = storage.UpdateStatus(recordingID, StatusTranscribeFailed)
+		_ = storage.SetLastError(recordingID, message)
+		emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, message, nil)
+		return nil
+	}
+	_ = storage.SetTranscriptDataFile(recordingID, result.TranscriptDataFilename)
+	_ = storage.SetTranscriptFile(recordingID, result.TranscriptFilename)
+	if result.SummaryFilename != "" {
+		_ = storage.SetSummaryFile(recordingID, result.SummaryFilename)
+	}
+	_ = storage.SetTitle(recordingID, result.Title)
+	_, _ = storage.UpdateStatus(recordingID, StatusTranscribed)
+	_ = storage.SetLastError(recordingID, "")
+	logger.Info("[asr-trigger] 转写完成: " + recordingID + ", summary=\"" + result.Title + "\"")
+	emitRecordingStatus(recordingID, storage, logger, opts.NotifyStatus, "", &StatusEvent{
+		Transcript: result.Transcript,
+		Summary:    result.Summary,
+		Title:      result.Title,
+	})
+	return nil
+}
+
+func emitRecordingStatus(recordingID string, storage *Storage, logger Logger, notify func(StatusEvent), errMessage string, extras *StatusEvent) {
+	if notify == nil {
+		return
+	}
+	entry, ok := storage.FindByID(recordingID)
+	if !ok {
+		return
+	}
+	title := entry.Title
+	if extras != nil && extras.Title != "" {
+		title = extras.Title
+	}
+	if title == "" {
+		title = entry.Metadata.Name
+	}
+	if title == "" {
+		title = entry.ID
+	}
+	persistedErr := entry.LastError
+	if errMessage == "" {
+		errMessage = persistedErr
+	}
+	event := StatusEvent{
+		RecordingID:        entry.ID,
+		TransferStatus:     entry.Status,
+		AudioFile:          entry.AudioFile,
+		SrtFile:            entry.SrtFile,
+		TranscriptDataFile: entry.TranscriptDataFile,
+		TranscriptFile:     entry.TranscriptFile,
+		Title:              title,
+		UpdatedAt:          entry.UpdatedAt,
+		Error:              errMessage,
+	}
+	if extras != nil {
+		event.Transcript = extras.Transcript
+		event.Summary = extras.Summary
+	}
+	defer func() {
+		if rec := recover(); rec != nil {
+			logger.Error(fmt.Sprintf("[recording-status] 状态事件发送失败: %s, %v", recordingID, rec))
+		}
+	}()
+	notify(event)
+}
diff --git a/internal/recording/handler_test.go b/internal/recording/handler_test.go
new file mode 100644
index 0000000..8ac5883
--- /dev/null
+++ b/internal/recording/handler_test.go
@@ -0,0 +1,161 @@
+package recording
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+type testLogger struct {
+	t *testing.T
+}
+
+func (l testLogger) Info(msg string)  { l.t.Log("[INFO] " + msg) }
+func (l testLogger) Warn(msg string)  { l.t.Log("[WARN] " + msg) }
+func (l testLogger) Error(msg string) { l.t.Log("[ERROR] " + msg) }
+
+func TestHandleRecordingSyncDownloadsFiles(t *testing.T) {
+	t.Parallel()
+	oss := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/rec.ogg":
+			_, _ = w.Write([]byte("audio-bytes"))
+		case "/rec.srt":
+			_, _ = w.Write([]byte("1\n00:00:00,000 --> 00:00:01,000\nhello\n"))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer oss.Close()
+
+	storage := NewStorage(filepath.Join(t.TempDir(), "recordings"), testLogger{t})
+	if err := storage.Init(); err != nil {
+		t.Fatal(err)
+	}
+	var eventsMu sync.Mutex
+	var events []StatusEvent
+	result := HandleRecordingSyncWithClientLabel("rec_1", Metadata{
+		Name: "测试录音", DurationSec: 1, FileSizeBytes: 12,
+		CreatedAt:   "2026-06-04T17:16:50+08:00",
+		OssAudioURL: oss.URL + "/rec.ogg",
+		OssSrtURL:   oss.URL + "/rec.srt",
+		Markers:     []Marker{{Index: 0, TimestampMS: 500}},
+	}, "phone-a", storage, nil, testLogger{t}, SyncOptions{
+		NotifyStatus: func(event StatusEvent) {
+			eventsMu.Lock()
+			defer eventsMu.Unlock()
+			events = append(events, event)
+		},
+		DownloadOptions: DownloadOptions{MaxRetries: 1},
+	})
+	if !result.OK || result.TransferStatus != StatusSyncingOpenClaw {
+		t.Fatalf("unexpected sync result: %+v", result)
+	}
+
+	waitFor(t, time.Second, func() bool {
+		entry, ok := storage.FindByID("rec_1")
+		return ok && entry.Status == StatusSynced && entry.AudioFile == "audio/rec_1.ogg" && entry.SrtFile == "audio/rec_1.srt"
+	})
+	entry, _ := storage.FindByID("rec_1")
+	if entry.ClientLabel != "phone-a" {
+		t.Fatalf("client label mismatch: %q", entry.ClientLabel)
+	}
+	audio, err := os.ReadFile(filepath.Join(storage.AudioDir(), "rec_1.ogg"))
+	if err != nil || string(audio) != "audio-bytes" {
+		t.Fatalf("audio file mismatch: %q err=%v", string(audio), err)
+	}
+	eventsMu.Lock()
+	defer eventsMu.Unlock()
+	if len(events) == 0 || events[len(events)-1].TransferStatus != StatusSynced {
+		t.Fatalf("missing synced event: %+v", events)
+	}
+}
+
+func TestRunTranscriptionWorkflowWithModelProxy(t *testing.T) {
+	t.Setenv("OPENCLAW_ASR_POLL_INTERVAL_MS", "1")
+	var sawSubmit bool
+	modelProxy := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/submit-task":
+			if r.Header.Get("X-Api-Key-Id") != "test-key" {
+				t.Fatalf("missing api key header")
+			}
+			var body map[string]any
+			if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+				t.Fatal(err)
+			}
+			if body["audioOssUrl"] != "https://oss.invalid/rec_asr.ogg" {
+				t.Fatalf("unexpected submit body: %+v", body)
+			}
+			sawSubmit = true
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"data": map[string]any{"taskId": "task1", "status": "RUNNING", "requestId": "req1"},
+			})
+		case "/query-task-result/task1":
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"data": map[string]any{
+					"taskId": "task1", "status": "SUCCEEDED", "requestId": "req2",
+					"recordResult": map[string]any{
+						"sourceTextList": []map[string]any{{"content": "你好", "speakerId": 1, "startTime": 0, "endTime": 1000}},
+						"summaryResult":  "摘要正文",
+						"title":          "测试标题",
+						"category":       "meeting",
+					},
+				},
+			})
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer modelProxy.Close()
+
+	storage := NewStorage(filepath.Join(t.TempDir(), "recordings"), testLogger{t})
+	if err := storage.Init(); err != nil {
+		t.Fatal(err)
+	}
+	audioPath := storage.AudioFilePath("rec_asr", "https://oss.invalid/rec_asr.ogg")
+	if err := os.WriteFile(audioPath, []byte("audio"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	result := RunTranscriptionWorkflow(storage, Entry{
+		ID: "rec_asr",
+		Metadata: Metadata{
+			Name: "ASR 录音", DurationSec: 1, CreatedAt: "2026-06-04T17:16:50+08:00",
+			OssAudioURL: "https://oss.invalid/rec_asr.ogg",
+		},
+	}, AsrConfig{Mode: "api", API: &AsrAPIConfig{APIKey: "test-key", Endpoint: modelProxy.URL + "/submit-task"}}, testLogger{t})
+	if !result.OK {
+		t.Fatalf("workflow failed: %+v", result)
+	}
+	if !sawSubmit {
+		t.Fatal("submit endpoint was not called")
+	}
+	raw, err := os.ReadFile(filepath.Join(storage.TranscriptDataDir(), result.TranscriptDataFilename))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var doc TranscriptDocument
+	if err := json.Unmarshal(raw, &doc); err != nil {
+		t.Fatal(err)
+	}
+	if doc.Normalized.Title != "测试标题" || doc.Normalized.Text != "你好" || len(doc.Normalized.Segments) != 1 {
+		t.Fatalf("unexpected transcript doc: %+v", doc.Normalized)
+	}
+}
+
+func waitFor(t *testing.T, timeout time.Duration, ok func() bool) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		if ok() {
+			return
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+	t.Fatal("condition not met before timeout")
+}
diff --git a/internal/recording/state.go b/internal/recording/state.go
new file mode 100644
index 0000000..8f98ce0
--- /dev/null
+++ b/internal/recording/state.go
@@ -0,0 +1,62 @@
+package recording
+
+import "fmt"
+
+const (
+	StatusReceivingFailed  = "receiving_failed"
+	StatusReceiving        = "receiving"
+	StatusPendingOSSUpload = "pending_oss_upload"
+	StatusUploadingOSS     = "uploading_oss"
+	StatusOSSUploaded      = "oss_uploaded"
+	StatusSyncingOpenClaw  = "syncing_openclaw"
+	StatusSyncFailed       = "sync_failed"
+	StatusSynced           = "synced"
+	StatusTranscribing     = "transcribing"
+	StatusTranscribeFailed = "transcribe_failed"
+	StatusTranscribed      = "transcribed"
+)
+
+var validTransitions = map[string]map[string]bool{
+	StatusReceivingFailed:  {StatusReceiving: true},
+	StatusReceiving:        {StatusPendingOSSUpload: true},
+	StatusPendingOSSUpload: {StatusUploadingOSS: true},
+	StatusUploadingOSS:     {StatusOSSUploaded: true},
+	StatusOSSUploaded:      {StatusSyncingOpenClaw: true},
+	StatusSyncingOpenClaw:  {StatusSynced: true, StatusSyncFailed: true},
+	StatusSyncFailed:       {StatusSyncingOpenClaw: true},
+	StatusSynced:           {StatusTranscribing: true},
+	StatusTranscribing:     {StatusTranscribed: true, StatusTranscribeFailed: true},
+	StatusTranscribeFailed: {StatusTranscribing: true},
+	StatusTranscribed:      {StatusTranscribing: true},
+}
+
+// TransitionError 表示非法状态流转。
+type TransitionError struct {
+	From string
+	To   string
+}
+
+func (e *TransitionError) Error() string {
+	return fmt.Sprintf("非法状态转换: %s -> %s", e.From, e.To)
+}
+
+// ValidateTransition 校验状态转换是否合法。
+func ValidateTransition(from, to string) error {
+	if allowed := validTransitions[from]; allowed != nil && allowed[to] {
+		return nil
+	}
+	return &TransitionError{From: from, To: to}
+}
+
+// CanStartTranscription 判断当前状态是否允许触发 ASR。
+func CanStartTranscription(status string) bool {
+	return status == StatusSynced || status == StatusTranscribeFailed || status == StatusTranscribed
+}
+
+// IsRecordingStatus 判断字符串是否为已知录音传输状态。
+func IsRecordingStatus(status string) bool {
+	if _, ok := validTransitions[status]; ok {
+		return true
+	}
+	return status == StatusTranscribed
+}
diff --git a/internal/recording/store.go b/internal/recording/store.go
index 4b322fc..13ecaf4 100644
--- a/internal/recording/store.go
+++ b/internal/recording/store.go
@@ -1,24 +1,53 @@
-// Package recording 读取录音索引（recordings/index.json）与状态事件流
-// （recordings/state/events.jsonl），对齐 TS 版 cli helpers + commands/recording.ts。
+// Package recording 读取/写入录音索引（recordings/index.json）与状态事件流
+// （recordings/state/events.jsonl），对齐 TS 版 vendor/recording。
 package recording
 
 import (
 	"encoding/json"
+	"net/url"
 	"os"
 	"path/filepath"
+	"regexp"
 	"sort"
 	"strings"
+	"sync"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+)
+
+const (
+	audioDirName          = "audio"
+	transcriptDataDirName = "transcript-data"
+	transcriptsDirName    = "transcripts"
+	summariesDirName      = "summaries"
+	indexFileName         = "index.json"
 )
 
+// Logger 是存储/同步层依赖的最小日志接口。
+type Logger interface {
+	Info(string)
+	Warn(string)
+	Error(string)
+}
+
+// Marker 是录音关键点标记。
+type Marker struct {
+	Index       int     `json:"index"`
+	TimestampMS float64 `json:"timestamp_ms"`
+}
+
 // Metadata 是录音元数据（index.json entry.metadata）。
 type Metadata struct {
-	Name          string  `json:"name"`
-	DurationSec   float64 `json:"duration_sec"`
-	FileSizeBytes int64   `json:"file_size_bytes"`
-	CreatedAt     string  `json:"created_at"`
-	Status        string  `json:"transfer_status"`
-	Location      any     `json:"location,omitempty"`
-	Markers       any     `json:"markers,omitempty"`
+	Name          string   `json:"name"`
+	DurationSec   float64  `json:"duration_sec"`
+	FileSizeBytes int64    `json:"file_size_bytes"`
+	CreatedAt     string   `json:"created_at"`
+	Status        string   `json:"transfer_status,omitempty"`
+	Location      any      `json:"location,omitempty"`
+	OssAudioURL   string   `json:"oss_audio_url"`
+	OssSrtURL     string   `json:"oss_srt_url,omitempty"`
+	Markers       []Marker `json:"markers,omitempty"`
 }
 
 // Entry 是一条录音索引项。
@@ -38,15 +67,415 @@ type Entry struct {
 	UpdatedAt          string   `json:"updatedAt"`
 }
 
+type indexWrapper struct {
+	Recordings []Entry `json:"recordings"`
+}
+
+// Storage 是 recordings/ 目录的写侧存储。
+type Storage struct {
+	dir               string
+	audioDir          string
+	transcriptDataDir string
+	transcriptsDir    string
+	summariesDir      string
+	indexPath         string
+	logger            Logger
+	mu                sync.Mutex
+	index             indexWrapper
+}
+
+// NewStorage 构造录音存储；dir 为 recordings 目录。
+func NewStorage(dir string, logger Logger) *Storage {
+	return &Storage{
+		dir:               dir,
+		audioDir:          filepath.Join(dir, audioDirName),
+		transcriptDataDir: filepath.Join(dir, transcriptDataDirName),
+		transcriptsDir:    filepath.Join(dir, transcriptsDirName),
+		summariesDir:      filepath.Join(dir, summariesDirName),
+		indexPath:         filepath.Join(dir, indexFileName),
+		logger:            logger,
+		index:             indexWrapper{Recordings: []Entry{}},
+	}
+}
+
+// Init 准备目录并加载索引。
+func (s *Storage) Init() error {
+	for _, dir := range []string{s.audioDir, s.transcriptDataDir, s.transcriptsDir, s.summariesDir} {
+		if err := fsutil.EnsureDir(dir, fsutil.DirMode); err != nil {
+			return err
+		}
+	}
+	s.loadIndex()
+	s.logger.Info("录音存储已初始化: " + s.dir)
+	return nil
+}
+
+// Close 当前无需额外清理。
+func (s *Storage) Close() error { return nil }
+
+func (s *Storage) loadIndex() {
+	var wrapper indexWrapper
+	exists, err := fsutil.ReadJSON(s.indexPath, &wrapper)
+	if err != nil || !exists || wrapper.Recordings == nil {
+		s.index = indexWrapper{Recordings: []Entry{}}
+		return
+	}
+	needsRewrite := false
+	now := nowISO()
+	for i := range wrapper.Recordings {
+		if wrapper.Recordings[i].Status == "transcribing" {
+			wrapper.Recordings[i].Status = "transcribe_failed"
+			if strings.TrimSpace(wrapper.Recordings[i].LastError) == "" {
+				wrapper.Recordings[i].LastError = "转写任务已中断，请重新发起转写"
+			}
+			wrapper.Recordings[i].UpdatedAt = now
+			needsRewrite = true
+		}
+	}
+	s.index = wrapper
+	if needsRewrite {
+		_ = s.saveIndexLocked()
+	}
+}
+
+func (s *Storage) saveIndexLocked() error {
+	return fsutil.WriteJSON(s.indexPath, s.index, fsutil.ConfigFileMode)
+}
+
+func nowISO() string { return time.Now().UTC().Format(time.RFC3339Nano) }
+
+// AudioDir 返回 audio/ 绝对路径。
+func (s *Storage) AudioDir() string { return s.audioDir }
+
+// TranscriptDataDir 返回 transcript-data/ 绝对路径。
+func (s *Storage) TranscriptDataDir() string { return s.transcriptDataDir }
+
+// TranscriptsDir 返回 transcripts/ 绝对路径。
+func (s *Storage) TranscriptsDir() string { return s.transcriptsDir }
+
+// SummariesDir 返回 summaries/ 绝对路径。
+func (s *Storage) SummariesDir() string { return s.summariesDir }
+
+// Ingest 收到 recordings.sync 后写入/更新元数据。
+func (s *Storage) Ingest(recordingID string, metadata Metadata, clientLabel string) (Entry, error) {
+	if clientLabel == "" {
+		clientLabel = "default"
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	now := nowISO()
+	if idx := s.findIndexLocked(recordingID); idx >= 0 {
+		entry := &s.index.Recordings[idx]
+		sameAudioURL := entry.Metadata.OssAudioURL == metadata.OssAudioURL
+		canPreserveSyncState := sameAudioURL &&
+			entry.AudioFile != "" &&
+			entry.Status != "syncing_openclaw" &&
+			entry.Status != "sync_failed"
+		if canPreserveSyncState {
+			entry.Metadata = metadata
+			entry.ClientLabel = clientLabel
+			entry.UpdatedAt = now
+			if err := s.saveIndexLocked(); err != nil {
+				return Entry{}, err
+			}
+			s.logger.Info("录音元数据已更新: " + recordingID + "（同音频，保留状态 " + entry.Status + "）")
+			return *entry, nil
+		}
+
+		s.removeRelativeLocked(entry.TranscriptDataFile)
+		s.removeRelativeLocked(entry.TranscriptFile)
+		s.removeRelativeLocked(entry.SummaryFile)
+		entry.Metadata = metadata
+		entry.ClientLabel = clientLabel
+		entry.Status = "syncing_openclaw"
+		entry.TranscriptDataFile = ""
+		entry.TranscriptFile = ""
+		entry.SummaryFile = ""
+		entry.Title = ""
+		entry.LastError = ""
+		entry.UpdatedAt = now
+		if err := s.saveIndexLocked(); err != nil {
+			return Entry{}, err
+		}
+		s.logger.Info("录音元数据已更新: " + recordingID)
+		return *entry, nil
+	}
+
+	entry := Entry{
+		ID:          recordingID,
+		ClientLabel: clientLabel,
+		Metadata:    metadata,
+		Status:      "syncing_openclaw",
+		IngestedAt:  now,
+		UpdatedAt:   now,
+	}
+	s.index.Recordings = append(s.index.Recordings, entry)
+	if err := s.saveIndexLocked(); err != nil {
+		return Entry{}, err
+	}
+	s.logger.Info("录音元数据已入库: " + recordingID)
+	return entry, nil
+}
+
+func (s *Storage) removeRelativeLocked(rel string) {
+	if rel == "" {
+		return
+	}
+	_ = os.Remove(filepath.Join(s.dir, rel))
+}
+
+// FindByID 查询单条录音，返回副本。
+func (s *Storage) FindByID(id string) (Entry, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	idx := s.findIndexLocked(id)
+	if idx < 0 {
+		return Entry{}, false
+	}
+	return s.index.Recordings[idx], true
+}
+
+func (s *Storage) findIndexLocked(id string) int {
+	for i, r := range s.index.Recordings {
+		if r.ID == id {
+			return i
+		}
+	}
+	return -1
+}
+
+// ListAll 返回按 created_at 倒序排列的录音副本。
+func (s *Storage) ListAll() []Entry {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := append([]Entry(nil), s.index.Recordings...)
+	SortByCreatedDesc(out)
+	return out
+}
+
+// ListByStatus 按状态过滤。
+func (s *Storage) ListByStatus(status string) []Entry {
+	all := s.ListAll()
+	out := all[:0]
+	for _, entry := range all {
+		if entry.Status == status {
+			out = append(out, entry)
+		}
+	}
+	return out
+}
+
+// Rename 更新录音名称。
+func (s *Storage) Rename(recordingID, name string) (Entry, bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	idx := s.findIndexLocked(recordingID)
+	if idx < 0 {
+		return Entry{}, false, nil
+	}
+	s.index.Recordings[idx].Metadata.Name = name
+	s.index.Recordings[idx].UpdatedAt = nowISO()
+	if err := s.saveIndexLocked(); err != nil {
+		return Entry{}, false, err
+	}
+	return s.index.Recordings[idx], true, nil
+}
+
+// Delete 删除录音。localOnly 为 true 时保留索引，仅清掉本地文件引用。
+func (s *Storage) Delete(recordingID string, localOnly bool) (bool, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	idx := s.findIndexLocked(recordingID)
+	if idx < 0 {
+		return false, nil
+	}
+	entry := &s.index.Recordings[idx]
+	for _, rel := range []string{entry.AudioFile, entry.SrtFile, entry.TranscriptDataFile, entry.TranscriptFile, entry.SummaryFile} {
+		s.removeRelativeLocked(rel)
+	}
+	if localOnly {
+		entry.AudioFile = ""
+		entry.SrtFile = ""
+		entry.TranscriptDataFile = ""
+		entry.TranscriptFile = ""
+		entry.SummaryFile = ""
+		entry.UpdatedAt = nowISO()
+	} else {
+		s.index.Recordings = append(s.index.Recordings[:idx], s.index.Recordings[idx+1:]...)
+	}
+	if err := s.saveIndexLocked(); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+// UpdateStatus 按状态机校验并更新状态。
+func (s *Storage) UpdateStatus(recordingID, newStatus string) (Entry, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	idx := s.findIndexLocked(recordingID)
+	if idx < 0 {
+		return Entry{}, os.ErrNotExist
+	}
+	entry := &s.index.Recordings[idx]
+	if err := ValidateTransition(entry.Status, newStatus); err != nil {
+		return Entry{}, err
+	}
+	entry.Status = newStatus
+	entry.UpdatedAt = nowISO()
+	if err := s.saveIndexLocked(); err != nil {
+		return Entry{}, err
+	}
+	s.logger.Info("录音状态更新: " + recordingID + " -> " + newStatus)
+	return *entry, nil
+}
+
+// SetAudioFile 记录本地音频文件。
+func (s *Storage) SetAudioFile(recordingID, filename string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		entry.AudioFile = audioDirName + "/" + filename
+	})
+}
+
+// SetSrtFile 记录本地打点文件。
+func (s *Storage) SetSrtFile(recordingID, filename string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		entry.SrtFile = audioDirName + "/" + filename
+	})
+}
+
+// SetTranscriptDataFile 记录转写 JSON 文件。
+func (s *Storage) SetTranscriptDataFile(recordingID, filename string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		next := transcriptDataDirName + "/" + filename
+		if entry.TranscriptDataFile != "" && entry.TranscriptDataFile != next {
+			s.removeRelativeLocked(entry.TranscriptDataFile)
+		}
+		entry.TranscriptDataFile = next
+	})
+}
+
+// SetTranscriptFile 记录转写 Markdown 文件。
+func (s *Storage) SetTranscriptFile(recordingID, filename string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		next := transcriptsDirName + "/" + filename
+		if entry.TranscriptFile != "" && entry.TranscriptFile != next {
+			s.removeRelativeLocked(entry.TranscriptFile)
+		}
+		entry.TranscriptFile = next
+	})
+}
+
+// SetSummaryFile 记录摘要文件。
+func (s *Storage) SetSummaryFile(recordingID, filename string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		next := summariesDirName + "/" + filename
+		if entry.SummaryFile != "" && entry.SummaryFile != next {
+			s.removeRelativeLocked(entry.SummaryFile)
+		}
+		entry.SummaryFile = next
+	})
+}
+
+// SetTitle 记录转写标题。
+func (s *Storage) SetTitle(recordingID, title string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		entry.Title = strings.TrimSpace(title)
+	})
+}
+
+// SetLastError 记录或清除最近错误。
+func (s *Storage) SetLastError(recordingID, message string) error {
+	return s.updateEntry(recordingID, func(entry *Entry) {
+		entry.LastError = strings.TrimSpace(message)
+	})
+}
+
+func (s *Storage) updateEntry(recordingID string, mutate func(*Entry)) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	idx := s.findIndexLocked(recordingID)
+	if idx < 0 {
+		return os.ErrNotExist
+	}
+	mutate(&s.index.Recordings[idx])
+	s.index.Recordings[idx].UpdatedAt = nowISO()
+	return s.saveIndexLocked()
+}
+
+// AudioFilename 生成音频文件名。
+func AudioFilename(recordingID, ossURL string) string {
+	return recordingID + extractAudioExt(ossURL)
+}
+
+// SrtFilename 生成打点文件名。
+func SrtFilename(recordingID string) string { return recordingID + ".srt" }
+
+// TranscriptDataFilename 生成转写 JSON 文件名。
+func TranscriptDataFilename(recordingID string) string { return recordingID + ".json" }
+
+// TranscriptFilename 生成转写 Markdown 文件名。
+func TranscriptFilename(recordingID, title string) string {
+	safe := sanitizeFilename(title)
+	if safe != "" {
+		return recordingID + "_" + safe + ".md"
+	}
+	return recordingID + ".md"
+}
+
+// SummaryFilename 生成摘要文件名。
+func SummaryFilename(recordingID string) string { return recordingID + ".md" }
+
+// AudioFilePath 返回音频文件绝对路径。
+func (s *Storage) AudioFilePath(recordingID, ossURL string) string {
+	return filepath.Join(s.audioDir, AudioFilename(recordingID, ossURL))
+}
+
+// SrtFilePath 返回打点文件绝对路径。
+func (s *Storage) SrtFilePath(recordingID string) string {
+	return filepath.Join(s.audioDir, SrtFilename(recordingID))
+}
+
+func extractAudioExt(rawURL string) string {
+	if rawURL != "" {
+		if u, err := url.Parse(rawURL); err == nil {
+			if ext := filepath.Ext(u.Path); validExt(ext) {
+				return strings.ToLower(ext)
+			}
+		}
+		if ext := filepath.Ext(strings.Split(rawURL, "?")[0]); validExt(ext) {
+			return strings.ToLower(ext)
+		}
+	}
+	return ".ogg"
+}
+
+func validExt(ext string) bool {
+	if ext == "" || len(ext) > 12 {
+		return false
+	}
+	return regexp.MustCompile(`^\.[A-Za-z0-9]+$`).MatchString(ext)
+}
+
+var badFilenameChars = strings.NewReplacer("/", "", "\\", "", ":", "", "*", "", "?", "", `"`, "", "<", "", ">", "", "|", "")
+
+func sanitizeFilename(s string) string {
+	out := strings.TrimSpace(badFilenameChars.Replace(s))
+	runes := []rune(out)
+	if len(runes) > 20 {
+		runes = runes[:20]
+	}
+	return strings.TrimSpace(string(runes))
+}
+
 // ReadIndex 读取 recordings/index.json 的 recordings[]；目录/文件不存在返回空。
 func ReadIndex(recordingsDir string) []Entry {
-	raw, err := os.ReadFile(filepath.Join(recordingsDir, "index.json"))
+	raw, err := os.ReadFile(filepath.Join(recordingsDir, indexFileName))
 	if err != nil {
 		return nil
 	}
-	var wrapper struct {
-		Recordings []Entry `json:"recordings"`
-	}
+	var wrapper indexWrapper
 	if json.Unmarshal(raw, &wrapper) != nil {
 		return nil
 	}
diff --git a/internal/recording/transcript.go b/internal/recording/transcript.go
new file mode 100644
index 0000000..2ead46d
--- /dev/null
+++ b/internal/recording/transcript.go
@@ -0,0 +1,231 @@
+package recording
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+const transcriptDocumentSchemaVersion = 1
+
+// TranscriptSource 是 transcript-data 的来源信息。
+type TranscriptSource struct {
+	Provider  string `json:"provider"`
+	TaskID    string `json:"taskId,omitempty"`
+	RequestID string `json:"requestId,omitempty"`
+	Status    string `json:"status,omitempty"`
+}
+
+// TranscriptSegment 是 transcript-data normalized.segments 的单段。
+type TranscriptSegment struct {
+	Text      string   `json:"text"`
+	StartMS   *float64 `json:"startMs,omitempty"`
+	EndMS     *float64 `json:"endMs,omitempty"`
+	SpeakerID *int     `json:"speakerId,omitempty"`
+}
+
+// TranscriptItem 是对客户端展示的 sourceTextList 形状。
+type TranscriptItem struct {
+	Content   string   `json:"content"`
+	SpeakerID *int     `json:"speakerId,omitempty"`
+	StartTime *float64 `json:"startTime,omitempty"`
+	EndTime   *float64 `json:"endTime,omitempty"`
+}
+
+// TranscriptDocument 是转写结构化主存储。
+type TranscriptDocument struct {
+	SchemaVersion int              `json:"schemaVersion"`
+	RecordingID   string           `json:"recordingId"`
+	GeneratedAt   string           `json:"generatedAt"`
+	Source        TranscriptSource `json:"source"`
+	Normalized    struct {
+		Title    string              `json:"title,omitempty"`
+		Category string              `json:"category,omitempty"`
+		Summary  string              `json:"summary"`
+		Text     string              `json:"text"`
+		Segments []TranscriptSegment `json:"segments"`
+	} `json:"normalized"`
+	Raw any `json:"raw,omitempty"`
+}
+
+// BuildTranscriptDocument 构造 transcript-data 文档。
+func BuildTranscriptDocument(recordingID string, source TranscriptSource, title, category, summary, text string, segments []TranscriptSegment, raw any) TranscriptDocument {
+	if text == "" && len(segments) > 0 {
+		parts := make([]string, 0, len(segments))
+		for _, s := range segments {
+			if strings.TrimSpace(s.Text) != "" {
+				parts = append(parts, strings.TrimSpace(s.Text))
+			}
+		}
+		text = strings.Join(parts, "\n\n")
+	}
+	doc := TranscriptDocument{
+		SchemaVersion: transcriptDocumentSchemaVersion,
+		RecordingID:   recordingID,
+		GeneratedAt:   nowISO(),
+		Source:        source,
+		Raw:           raw,
+	}
+	doc.Normalized.Title = strings.TrimSpace(title)
+	doc.Normalized.Category = strings.TrimSpace(category)
+	doc.Normalized.Summary = strings.TrimSpace(summary)
+	doc.Normalized.Text = strings.TrimSpace(text)
+	doc.Normalized.Segments = segments
+	return doc
+}
+
+// ExtractSourceTextListFromDocument 生成客户端 transcript[] 形状。
+func ExtractSourceTextListFromDocument(doc TranscriptDocument) []TranscriptItem {
+	if len(doc.Normalized.Segments) > 0 {
+		out := make([]TranscriptItem, 0, len(doc.Normalized.Segments))
+		for _, seg := range doc.Normalized.Segments {
+			if strings.TrimSpace(seg.Text) == "" {
+				continue
+			}
+			out = append(out, TranscriptItem{
+				Content:   seg.Text,
+				SpeakerID: seg.SpeakerID,
+				StartTime: seg.StartMS,
+				EndTime:   seg.EndMS,
+			})
+		}
+		if len(out) > 0 {
+			return out
+		}
+	}
+	if strings.TrimSpace(doc.Normalized.Text) != "" {
+		return []TranscriptItem{{Content: doc.Normalized.Text}}
+	}
+	return nil
+}
+
+// ParseTranscriptDocument 解析 transcript-data 文档。
+func ParseTranscriptDocument(raw []byte) (TranscriptDocument, bool) {
+	var doc TranscriptDocument
+	if json.Unmarshal(raw, &doc) != nil {
+		return TranscriptDocument{}, false
+	}
+	if doc.RecordingID == "" || doc.GeneratedAt == "" || doc.Source.Provider == "" {
+		return TranscriptDocument{}, false
+	}
+	return doc, true
+}
+
+// BuildTranscriptMarkdown 生成转写 Markdown。
+func BuildTranscriptMarkdown(result TranscriptionResult, markers []Marker, recordingName string, durationSec float64, createdAt string) string {
+	title := strings.TrimSpace(result.Summary)
+	if title == "" {
+		title = strings.TrimSpace(recordingName)
+	}
+	if title == "" {
+		title = "录音转写"
+	}
+	if len([]rune(title)) > 10 {
+		title = string([]rune(title)[:10])
+	}
+
+	var lines []string
+	lines = append(lines, "# "+title, "")
+	lines = append(lines, "> 录音名称："+recordingName)
+	lines = append(lines, "> 时长："+formatDuration(durationSec))
+	lines = append(lines, "> 创建时间："+createdAt)
+	if len(markers) > 0 {
+		lines = append(lines, fmt.Sprintf("> 关键点数：%d", len(markers)))
+	}
+	lines = append(lines, "", "---", "")
+
+	if len(result.Segments) > 0 {
+		sorted := append([]Marker(nil), markers...)
+		sortMarkers(sorted)
+		markerIdx := 0
+		for _, seg := range result.Segments {
+			for markerIdx < len(sorted) && sorted[markerIdx].TimestampMS <= valueOrZero(seg.StartMS) {
+				lines = append(lines, "**[关键点 "+formatTimestamp(sorted[markerIdx].TimestampMS)+"]**", "")
+				markerIdx++
+			}
+			if text := formatTranscriptSegmentText(seg); text != "" {
+				lines = append(lines, text, "")
+			}
+		}
+		for markerIdx < len(sorted) {
+			lines = append(lines, "**[关键点 "+formatTimestamp(sorted[markerIdx].TimestampMS)+"]**", "")
+			markerIdx++
+		}
+	} else if strings.TrimSpace(result.Text) != "" {
+		if len(markers) > 0 {
+			lines = append(lines, "### 关键点", "")
+			for _, marker := range markers {
+				lines = append(lines, "- **[关键点 "+formatTimestamp(marker.TimestampMS)+"]**")
+			}
+			lines = append(lines, "", "---", "")
+		}
+		lines = append(lines, result.Text, "")
+	}
+
+	return strings.Join(lines, "\n")
+}
+
+func sortMarkers(markers []Marker) {
+	for i := 1; i < len(markers); i++ {
+		for j := i; j > 0 && markers[j-1].TimestampMS > markers[j].TimestampMS; j-- {
+			markers[j-1], markers[j] = markers[j], markers[j-1]
+		}
+	}
+}
+
+func valueOrZero(v *float64) float64 {
+	if v == nil {
+		return 0
+	}
+	return *v
+}
+
+func formatTranscriptSegmentText(seg TranscriptSegment) string {
+	text := strings.TrimSpace(seg.Text)
+	if text == "" {
+		return ""
+	}
+	prefix := ""
+	if seg.StartMS != nil {
+		prefix = "[" + formatTimestamp(*seg.StartMS) + "] "
+	}
+	if seg.SpeakerID != nil {
+		prefix += fmt.Sprintf("说话人%d：", *seg.SpeakerID)
+	}
+	return prefix + text
+}
+
+func formatTimestamp(ms float64) string {
+	total := int(ms / 1000)
+	min := total / 60
+	sec := total % 60
+	return fmt.Sprintf("%02d:%02d", min, sec)
+}
+
+func formatDuration(seconds float64) string {
+	total := int(seconds)
+	h := total / 3600
+	m := (total % 3600) / 60
+	s := total % 60
+	if h > 0 {
+		return fmt.Sprintf("%d:%02d:%02d", h, m, s)
+	}
+	return fmt.Sprintf("%d:%02d", m, s)
+}
+
+func extractSummary(text string) string {
+	for _, part := range strings.FieldsFunc(text, func(r rune) bool {
+		return r == '。' || r == '！' || r == '？' || r == '\n'
+	}) {
+		trimmed := strings.TrimSpace(part)
+		if trimmed == "" {
+			continue
+		}
+		runes := []rune(trimmed)
+		if len(runes) <= 10 {
+			return trimmed
+		}
+		return string(runes[:10])
+	}
+	return "录音转写"
+}
diff --git a/internal/relay/client.go b/internal/relay/client.go
new file mode 100644
index 0000000..6ca683f
--- /dev/null
+++ b/internal/relay/client.go
@@ -0,0 +1,482 @@
+package relay
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/YoooClaw/cli/internal/fsutil"
+	"github.com/gorilla/websocket"
+)
+
+// Credential 是 Relay WS 建连凭据。
+type Credential struct {
+	Query   map[string]string
+	Headers map[string]string
+}
+
+// CredentialProvider 每次重连时提供最新凭据。
+type CredentialProvider func() (Credential, error)
+
+// ClientOptions 是 RelayClient 配置。
+type ClientOptions struct {
+	TunnelURL          string
+	CredentialProvider CredentialProvider
+	HeartbeatSec       int
+	ReconnectBackoffMs int
+	StatusFilePath     string
+	Logger             Logger
+}
+
+// Client 负责 Relay WebSocket 建连、心跳、重连与 frame 分发。
+type Client struct {
+	opts ClientOptions
+
+	mu        sync.Mutex
+	conn      *websocket.Conn
+	writeMu   sync.Mutex
+	stopCh    chan struct{}
+	stoppedCh chan struct{}
+	stopOnce  sync.Once
+
+	handlersMu           sync.Mutex
+	inboundHandlers      []func(Frame)
+	connectedHandlers    []func()
+	disconnectedHandlers []func(string)
+
+	stateMu              sync.Mutex
+	connected            bool
+	reconnectAttempt     int
+	lastDisconnectReason string
+	lastInboundAt        time.Time
+}
+
+// NewClient 构造 Relay client。
+func NewClient(opts ClientOptions) *Client {
+	if opts.HeartbeatSec <= 0 {
+		opts.HeartbeatSec = defaultHeartbeatSec
+	}
+	if opts.ReconnectBackoffMs <= 0 {
+		opts.ReconnectBackoffMs = defaultReconnectBackoffMs
+	}
+	return &Client{opts: opts, stopCh: make(chan struct{}), stoppedCh: make(chan struct{})}
+}
+
+// OnInbound 注册入站 frame handler。
+func (c *Client) OnInbound(handler func(Frame)) {
+	c.handlersMu.Lock()
+	defer c.handlersMu.Unlock()
+	c.inboundHandlers = append(c.inboundHandlers, handler)
+}
+
+// OnConnected 注册连接成功回调。
+func (c *Client) OnConnected(handler func()) {
+	c.handlersMu.Lock()
+	defer c.handlersMu.Unlock()
+	c.connectedHandlers = append(c.connectedHandlers, handler)
+}
+
+// OnDisconnected 注册断开回调。
+func (c *Client) OnDisconnected(handler func(string)) {
+	c.handlersMu.Lock()
+	defer c.handlersMu.Unlock()
+	c.disconnectedHandlers = append(c.disconnectedHandlers, handler)
+}
+
+// Start 非阻塞启动自动重连循环。
+func (c *Client) Start() {
+	go c.run()
+}
+
+func (c *Client) run() {
+	defer close(c.stoppedCh)
+	for {
+		select {
+		case <-c.stopCh:
+			return
+		default:
+		}
+		err := c.connectOnce()
+		select {
+		case <-c.stopCh:
+			return
+		default:
+		}
+		reason := "unknown"
+		if err != nil {
+			reason = err.Error()
+		}
+		c.setDisconnected(reason)
+		c.emitDisconnected(reason)
+		delay := c.nextReconnectDelay()
+		c.opts.Logger.Info(fmt.Sprintf("Relay tunnel: reconnecting in %s (attempt %d)", delay, c.Status().ReconnectAttempt))
+		timer := time.NewTimer(delay)
+		select {
+		case <-timer.C:
+		case <-c.stopCh:
+			timer.Stop()
+			return
+		}
+	}
+}
+
+func (c *Client) connectOnce() error {
+	credential, err := c.opts.CredentialProvider()
+	if err != nil {
+		return fmt.Errorf("credential-error: %w", err)
+	}
+	wsURL, headers, err := c.buildURLAndHeaders(credential)
+	if err != nil {
+		return err
+	}
+	c.opts.Logger.Info("Relay tunnel: connecting to " + redactURL(wsURL.String()))
+	c.writeStatus("connecting", "")
+
+	dialer := websocket.Dialer{HandshakeTimeout: handshakeTimeout}
+	connCh := make(chan struct {
+		conn *websocket.Conn
+		resp *http.Response
+		err  error
+	}, 1)
+	go func() {
+		conn, resp, err := dialer.Dial(wsURL.String(), headers)
+		connCh <- struct {
+			conn *websocket.Conn
+			resp *http.Response
+			err  error
+		}{conn: conn, resp: resp, err: err}
+	}()
+	var result struct {
+		conn *websocket.Conn
+		resp *http.Response
+		err  error
+	}
+	select {
+	case result = <-connCh:
+	case <-time.After(connectWatchdog):
+		return fmt.Errorf("connect-watchdog-timeout")
+	case <-c.stopCh:
+		return fmt.Errorf("stopped")
+	}
+	if result.err != nil {
+		status := ""
+		if result.resp != nil {
+			status = result.resp.Status
+		}
+		if status != "" {
+			return fmt.Errorf("websocket dial failed: %s (%s)", result.err.Error(), status)
+		}
+		return fmt.Errorf("websocket dial failed: %w", result.err)
+	}
+	conn := result.conn
+	defer conn.Close()
+
+	c.mu.Lock()
+	c.conn = conn
+	c.mu.Unlock()
+	c.setConnected()
+	c.emitConnected()
+	c.writeStatus("connected", "")
+	c.opts.Logger.Info("Relay tunnel: connected, heartbeat started")
+
+	readDone := make(chan error, 1)
+	heartbeatDone := make(chan error, 1)
+	conn.SetPongHandler(func(_ string) error {
+		c.markInbound()
+		c.opts.Logger.Info("Relay tunnel: <- pong received")
+		return nil
+	})
+	go c.readLoop(conn, readDone)
+	go c.heartbeatLoop(conn, heartbeatDone)
+
+	select {
+	case err := <-readDone:
+		return err
+	case err := <-heartbeatDone:
+		return err
+	case <-c.stopCh:
+		_ = conn.WriteControl(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseNormalClosure, "client stopping"), time.Now().Add(time.Second))
+		return fmt.Errorf("stopped")
+	}
+}
+
+func (c *Client) buildURLAndHeaders(credential Credential) (*url.URL, http.Header, error) {
+	wsURL, err := url.Parse(c.opts.TunnelURL)
+	if err != nil {
+		return nil, nil, err
+	}
+	for k, v := range credential.Query {
+		if wsURL.Query().Get(k) == "" {
+			q := wsURL.Query()
+			q.Set(k, v)
+			wsURL.RawQuery = q.Encode()
+		}
+	}
+	headers := http.Header{}
+	for k, v := range credential.Headers {
+		headers.Set(k, v)
+	}
+	return wsURL, headers, nil
+}
+
+func (c *Client) readLoop(conn *websocket.Conn, done chan<- error) {
+	for {
+		msgType, data, err := conn.ReadMessage()
+		if err != nil {
+			done <- fmt.Errorf("read failed: %w", err)
+			return
+		}
+		c.markInbound()
+		if msgType != websocket.TextMessage && msgType != websocket.BinaryMessage {
+			continue
+		}
+		text := string(data)
+		if text == "pong" {
+			continue
+		}
+		c.opts.Logger.Info(fmt.Sprintf("Relay tunnel: received message (%d chars): %s", len(text), preview(text, 500)))
+		var frame Frame
+		if err := json.Unmarshal(data, &frame); err != nil {
+			c.opts.Logger.Warn("Relay tunnel: received invalid frame, ignoring")
+			continue
+		}
+		c.handlersMu.Lock()
+		handlers := append([]func(Frame){}, c.inboundHandlers...)
+		c.handlersMu.Unlock()
+		for _, handler := range handlers {
+			h := handler
+			go func() {
+				defer func() {
+					if rec := recover(); rec != nil {
+						c.opts.Logger.Error(fmt.Sprintf("Relay tunnel: handler panic: %v", rec))
+					}
+				}()
+				h(frame)
+			}()
+		}
+	}
+}
+
+func (c *Client) heartbeatLoop(conn *websocket.Conn, done chan<- error) {
+	interval := time.Duration(c.opts.HeartbeatSec) * time.Second
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	if err := c.sendHeartbeat(conn); err != nil {
+		done <- err
+		return
+	}
+	for {
+		select {
+		case <-ticker.C:
+			if err := c.sendHeartbeat(conn); err != nil {
+				done <- err
+				return
+			}
+		case <-c.stopCh:
+			done <- fmt.Errorf("stopped")
+			return
+		}
+	}
+}
+
+func (c *Client) sendHeartbeat(conn *websocket.Conn) error {
+	timeout := time.Duration(c.opts.HeartbeatSec*3) * time.Second
+	if idle := time.Since(c.lastInbound()); idle >= timeout {
+		_ = conn.Close()
+		return fmt.Errorf("heartbeat-timeout idleMs=%d", idle.Milliseconds())
+	}
+	c.opts.Logger.Info(`Relay tunnel: -> heartbeat "ping"`)
+	c.writeMu.Lock()
+	defer c.writeMu.Unlock()
+	if err := conn.WriteMessage(websocket.TextMessage, []byte("ping")); err != nil {
+		_ = conn.Close()
+		return fmt.Errorf("heartbeat text ping failed: %w", err)
+	}
+	if err := conn.WriteControl(websocket.PingMessage, nil, time.Now().Add(5*time.Second)); err != nil {
+		_ = conn.Close()
+		return fmt.Errorf("heartbeat control ping failed: %w", err)
+	}
+	return nil
+}
+
+// Send sends a JSON frame.
+func (c *Client) Send(v any) {
+	payload, err := json.Marshal(v)
+	if err != nil {
+		c.opts.Logger.Warn("Relay tunnel: marshal frame failed: " + err.Error())
+		return
+	}
+	c.SendRaw(string(payload))
+}
+
+// SendRaw 原样发送文本到 Relay。
+func (c *Client) SendRaw(text string) {
+	c.mu.Lock()
+	conn := c.conn
+	c.mu.Unlock()
+	if conn == nil {
+		c.opts.Logger.Warn("Relay tunnel: sendRaw skipped, ws not open")
+		return
+	}
+	c.writeMu.Lock()
+	defer c.writeMu.Unlock()
+	if err := conn.WriteMessage(websocket.TextMessage, []byte(text)); err != nil {
+		c.opts.Logger.Warn("Relay tunnel: sendRaw failed: " + err.Error())
+		_ = conn.Close()
+	}
+}
+
+// Stop 优雅停止客户端。
+func (c *Client) Stop(reason string) {
+	c.stopOnce.Do(func() {
+		close(c.stopCh)
+		c.mu.Lock()
+		conn := c.conn
+		c.conn = nil
+		c.mu.Unlock()
+		if conn != nil {
+			_ = conn.WriteControl(websocket.CloseMessage, websocket.FormatCloseMessage(websocket.CloseNormalClosure, reason), time.Now().Add(time.Second))
+			_ = conn.Close()
+		}
+		c.writeStatus("stopped", "")
+	})
+	<-c.stoppedCh
+}
+
+// IsConnected 报告是否已连接。
+func (c *Client) IsConnected() bool {
+	return c.Status().Connected
+}
+
+// Status 返回连接状态。
+func (c *Client) Status() Status {
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	return Status{
+		Connected:            c.connected,
+		URL:                  c.opts.TunnelURL,
+		ReconnectAttempt:     c.reconnectAttempt,
+		LastDisconnectReason: c.lastDisconnectReason,
+	}
+}
+
+func (c *Client) setConnected() {
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	c.connected = true
+	c.reconnectAttempt = 0
+	c.lastDisconnectReason = ""
+	c.lastInboundAt = time.Now()
+}
+
+func (c *Client) setDisconnected(reason string) {
+	c.mu.Lock()
+	c.conn = nil
+	c.mu.Unlock()
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	c.connected = false
+	c.lastDisconnectReason = reason
+}
+
+func (c *Client) nextReconnectDelay() time.Duration {
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	delay := time.Duration(c.opts.ReconnectBackoffMs) * time.Millisecond * time.Duration(1<<min(c.reconnectAttempt, 10))
+	if delay > time.Minute {
+		delay = time.Minute
+	}
+	c.reconnectAttempt++
+	return delay
+}
+
+func (c *Client) markInbound() {
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	c.lastInboundAt = time.Now()
+}
+
+func (c *Client) lastInbound() time.Time {
+	c.stateMu.Lock()
+	defer c.stateMu.Unlock()
+	return c.lastInboundAt
+}
+
+func (c *Client) emitConnected() {
+	c.handlersMu.Lock()
+	handlers := append([]func(){}, c.connectedHandlers...)
+	c.handlersMu.Unlock()
+	for _, h := range handlers {
+		go h()
+	}
+}
+
+func (c *Client) emitDisconnected(reason string) {
+	c.writeStatus("disconnected", reason)
+	c.handlersMu.Lock()
+	handlers := append([]func(string){}, c.disconnectedHandlers...)
+	c.handlersMu.Unlock()
+	for _, h := range handlers {
+		handler := h
+		go handler(reason)
+	}
+}
+
+func (c *Client) writeStatus(state, reason string) {
+	if c.opts.StatusFilePath == "" {
+		return
+	}
+	payload := map[string]any{
+		"state":            state,
+		"since":            time.Now().UTC().Format(time.RFC3339Nano),
+		"reconnectAttempt": c.Status().ReconnectAttempt,
+	}
+	if reason != "" {
+		payload["lastDisconnectReason"] = reason
+	}
+	data, _ := json.MarshalIndent(payload, "", "  ")
+	_ = fsutil.EnsureDir(filepath.Dir(c.opts.StatusFilePath), fsutil.DirMode)
+	_ = os.WriteFile(c.opts.StatusFilePath, append(data, '\n'), 0o600)
+}
+
+func relayCredential(apiKey string) Credential {
+	raw := strings.TrimPrefix(strings.TrimSpace(apiKey), "Bearer ")
+	return Credential{Query: map[string]string{"apiKey": raw}}
+}
+
+func redactURL(raw string) string {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return raw
+	}
+	if v := u.Query().Get("apiKey"); v != "" {
+		q := u.Query()
+		if len(v) > 8 {
+			q.Set("apiKey", v[:8]+"...")
+		} else {
+			q.Set("apiKey", "...")
+		}
+		u.RawQuery = q.Encode()
+	}
+	return u.String()
+}
+
+func preview(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max] + "..."
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
diff --git a/internal/relay/dispatcher.go b/internal/relay/dispatcher.go
new file mode 100644
index 0000000..e601b9b
--- /dev/null
+++ b/internal/relay/dispatcher.go
@@ -0,0 +1,372 @@
+package relay
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+// Dispatcher 把 Relay 入站 frame loopback 到 daemon 自己的 HTTP/gateway 路由。
+type Dispatcher struct {
+	client      *Client
+	httpBaseURL string
+	httpToken   string
+	clientLabel string
+	logger      Logger
+
+	wsMu sync.Mutex
+	ws   map[string]*websocket.Conn
+}
+
+// DispatcherOptions 是 Dispatcher 配置。
+type DispatcherOptions struct {
+	Client      *Client
+	HTTPBaseURL string
+	HTTPToken   string
+	ClientLabel string
+	Logger      Logger
+}
+
+// NewDispatcher 构造 frame dispatcher。
+func NewDispatcher(opts DispatcherOptions) *Dispatcher {
+	return &Dispatcher{
+		client: opts.Client, httpBaseURL: strings.TrimRight(opts.HTTPBaseURL, "/"), httpToken: opts.HTTPToken,
+		clientLabel: opts.ClientLabel, logger: opts.Logger, ws: map[string]*websocket.Conn{},
+	}
+}
+
+// Start 绑定 client 入站 frame。
+func (d *Dispatcher) Start() {
+	d.client.OnInbound(func(frame Frame) {
+		d.handleFrame(frame)
+	})
+}
+
+// Cleanup 关闭所有本地 WS 子通道。
+func (d *Dispatcher) Cleanup() {
+	d.wsMu.Lock()
+	defer d.wsMu.Unlock()
+	for id, conn := range d.ws {
+		d.logger.Info("Relay dispatcher: closing local WS id=" + id)
+		_ = conn.Close()
+	}
+	d.ws = map[string]*websocket.Conn{}
+}
+
+// PushEvent daemon 主动推 Gateway event 给手机端。
+func (d *Dispatcher) PushEvent(event string, payload any) {
+	d.client.Send(EventFrame{Type: "event", Event: event, Payload: payload})
+}
+
+func (d *Dispatcher) handleFrame(frame Frame) {
+	typ, _ := frame["type"].(string)
+	id, _ := frame["id"].(string)
+	d.logger.Info(fmt.Sprintf("Relay dispatcher: handling frame type=%s id=%s", typ, firstNonEmpty(id, "N/A")))
+	switch typ {
+	case "req":
+		go d.handleReq(frame)
+	case "request":
+		go d.handleRequest(frame)
+	case "ws_open":
+		go d.handleWSOpen(frame)
+	case "ws_data":
+		d.handleWSData(frame)
+	case "ws_close":
+		d.handleWSClose(frame)
+	default:
+		d.logger.Warn("Relay dispatcher: unknown frame type=" + typ)
+	}
+}
+
+func (d *Dispatcher) handleReq(frame Frame) {
+	id := stringField(frame, "id")
+	method := stringField(frame, "method")
+	params := frame["params"]
+	if params == nil {
+		params = map[string]any{}
+	}
+	d.logger.Info("Relay dispatcher: req id=" + id + " method=" + method)
+	raw, status, err := d.loopbackJSON(http.MethodPost, "/gateway/"+url.PathEscape(method), params, nil)
+	if err != nil {
+		d.client.Send(RPCResponseFrame{Type: "res", ID: id, OK: false, Error: map[string]any{"code": "INTERNAL_ERROR", "message": err.Error()}})
+		return
+	}
+	if status < 200 || status >= 300 {
+		d.client.Send(RPCResponseFrame{Type: "res", ID: id, OK: false, Error: map[string]any{"code": "HTTP_ERROR", "message": fmt.Sprintf("daemon gateway returned %d: %s", status, preview(string(raw), 200))}})
+		return
+	}
+	var body struct {
+		OK    bool            `json:"ok"`
+		Data  json.RawMessage `json:"data"`
+		Error json.RawMessage `json:"error"`
+	}
+	if err := json.Unmarshal(raw, &body); err != nil {
+		d.client.Send(RPCResponseFrame{Type: "res", ID: id, OK: false, Error: map[string]any{"code": "INVALID_GATEWAY_RESPONSE", "message": err.Error()}})
+		return
+	}
+	resp := RPCResponseFrame{Type: "res", ID: id, OK: body.OK}
+	if body.OK {
+		var payload any
+		if len(body.Data) > 0 && string(body.Data) != "null" {
+			_ = json.Unmarshal(body.Data, &payload)
+		}
+		resp.Payload = payload
+	} else {
+		var errPayload any
+		if len(body.Error) > 0 {
+			_ = json.Unmarshal(body.Error, &errPayload)
+		}
+		resp.Error = errPayload
+	}
+	d.client.Send(resp)
+}
+
+func (d *Dispatcher) handleRequest(frame Frame) {
+	id := stringField(frame, "id")
+	method := firstNonEmpty(stringField(frame, "method"), http.MethodGet)
+	path := mapPath(stringField(frame, "path"))
+	body := stringField(frame, "body")
+	headers := headersFromFrame(frame["headers"])
+	for k := range headers {
+		lower := strings.ToLower(k)
+		if lower == "authorization" || lower == "x-openclaw-password" {
+			delete(headers, k)
+		}
+	}
+	d.addInternalHeaders(headers)
+
+	target := d.httpBaseURL + path
+	d.logger.Info(fmt.Sprintf("Relay dispatcher: request id=%s %s %s -> %s", id, method, stringField(frame, "path"), path))
+	req, err := http.NewRequest(method, target, requestBody(method, body))
+	if err != nil {
+		d.sendProxyError(id, 502, err.Error())
+		return
+	}
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		d.sendProxyError(id, 502, "daemon loopback failed: "+err.Error())
+		return
+	}
+	defer res.Body.Close()
+	contentType := res.Header.Get("Content-Type")
+	if strings.Contains(contentType, "text/event-stream") {
+		d.streamResponse(id, res.Body)
+		return
+	}
+	raw, _ := io.ReadAll(res.Body)
+	d.client.Send(ProxyResponseFrame{Type: "proxy_response", ID: id, Status: res.StatusCode, Headers: flattenHeaders(res.Header), Body: string(raw)})
+}
+
+func (d *Dispatcher) streamResponse(id string, body io.Reader) {
+	buf := make([]byte, 32*1024)
+	for {
+		n, err := body.Read(buf)
+		if n > 0 {
+			d.client.Send(StreamFrame{Type: "stream", ID: id, State: "delta", Data: string(buf[:n])})
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			d.sendProxyError(id, 502, "stream error: "+err.Error())
+			return
+		}
+	}
+	d.client.Send(StreamFrame{Type: "stream", ID: id, State: "end", Data: ""})
+}
+
+func (d *Dispatcher) handleWSOpen(frame Frame) {
+	id := stringField(frame, "id")
+	path := mapPath(stringField(frame, "path"))
+	wsURL := "ws" + strings.TrimPrefix(d.httpBaseURL, "http") + path
+	headers := http.Header{}
+	for k, v := range headersFromFrame(frame["headers"]) {
+		headers.Set(k, v)
+	}
+	d.addInternalHeadersMap(headers)
+	d.logger.Info(fmt.Sprintf("Relay dispatcher: ws_open id=%s path=%s -> %s", id, path, wsURL))
+	dialer := websocket.Dialer{HandshakeTimeout: 10 * time.Second}
+	conn, _, err := dialer.Dial(wsURL, headers)
+	if err != nil {
+		d.client.Send(WSCloseFrame{Type: "ws_close", ID: id, Code: 1011, Reason: "failed to connect: " + err.Error()})
+		return
+	}
+	d.wsMu.Lock()
+	if old := d.ws[id]; old != nil {
+		_ = old.Close()
+	}
+	d.ws[id] = conn
+	d.wsMu.Unlock()
+	d.client.Send(WSOpenedFrame{Type: "ws_opened", ID: id})
+	go d.readLocalWS(id, conn)
+}
+
+func (d *Dispatcher) readLocalWS(id string, conn *websocket.Conn) {
+	defer func() {
+		d.wsMu.Lock()
+		if d.ws[id] == conn {
+			delete(d.ws, id)
+		}
+		d.wsMu.Unlock()
+		_ = conn.Close()
+	}()
+	for {
+		msgType, data, err := conn.ReadMessage()
+		if err != nil {
+			d.client.Send(WSCloseFrame{Type: "ws_close", ID: id, Code: 1006, Reason: err.Error()})
+			return
+		}
+		if msgType == websocket.TextMessage || msgType == websocket.BinaryMessage {
+			d.client.Send(WSDataFrame{Type: "ws_data", ID: id, Data: string(data)})
+		}
+	}
+}
+
+func (d *Dispatcher) handleWSData(frame Frame) {
+	id := stringField(frame, "id")
+	data := stringField(frame, "data")
+	d.wsMu.Lock()
+	conn := d.ws[id]
+	d.wsMu.Unlock()
+	if conn == nil {
+		d.logger.Warn("Relay dispatcher: ws_data dropped, connection not found id=" + id)
+		return
+	}
+	if err := conn.WriteMessage(websocket.TextMessage, []byte(data)); err != nil {
+		d.logger.Warn("Relay dispatcher: ws_data write failed id=" + id + ": " + err.Error())
+		_ = conn.Close()
+	}
+}
+
+func (d *Dispatcher) handleWSClose(frame Frame) {
+	id := stringField(frame, "id")
+	d.wsMu.Lock()
+	conn := d.ws[id]
+	delete(d.ws, id)
+	d.wsMu.Unlock()
+	if conn != nil {
+		code := intField(frame, "code", websocket.CloseNormalClosure)
+		reason := stringField(frame, "reason")
+		_ = conn.WriteControl(websocket.CloseMessage, websocket.FormatCloseMessage(code, reason), time.Now().Add(time.Second))
+		_ = conn.Close()
+	}
+}
+
+func (d *Dispatcher) loopbackJSON(method, path string, body any, extra map[string]string) ([]byte, int, error) {
+	payload, _ := json.Marshal(body)
+	req, err := http.NewRequest(method, d.httpBaseURL+path, bytes.NewReader(payload))
+	if err != nil {
+		return nil, 0, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	headers := map[string]string{}
+	for k, v := range extra {
+		headers[k] = v
+	}
+	d.addInternalHeaders(headers)
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer res.Body.Close()
+	raw, err := io.ReadAll(res.Body)
+	return raw, res.StatusCode, err
+}
+
+func (d *Dispatcher) addInternalHeaders(headers map[string]string) {
+	headers[InternalHTTPHeader] = "1"
+	headers[InternalClientLabelHeader] = d.clientLabel
+	if d.httpToken != "" {
+		headers["Authorization"] = "Bearer " + d.httpToken
+	}
+}
+
+func (d *Dispatcher) addInternalHeadersMap(headers http.Header) {
+	headers.Set(InternalHTTPHeader, "1")
+	headers.Set(InternalClientLabelHeader, d.clientLabel)
+	if d.httpToken != "" {
+		headers.Set("Authorization", "Bearer "+d.httpToken)
+	}
+}
+
+func (d *Dispatcher) sendProxyError(id string, status int, message string) {
+	d.client.Send(ProxyErrorFrame{Type: "proxy_error", ID: id, Status: status, Message: message})
+}
+
+func mapPath(p string) string {
+	if p == "/api/message/messageBridge/send" {
+		return "/notifications"
+	}
+	if strings.HasPrefix(p, "/") {
+		return p
+	}
+	return "/" + p
+}
+
+func requestBody(method, body string) io.Reader {
+	if method == http.MethodGet || method == http.MethodHead {
+		return nil
+	}
+	return strings.NewReader(body)
+}
+
+func headersFromFrame(v any) map[string]string {
+	out := map[string]string{}
+	if m, ok := v.(map[string]any); ok {
+		for k, raw := range m {
+			if s, ok := raw.(string); ok {
+				out[k] = s
+			}
+		}
+	}
+	return out
+}
+
+func flattenHeaders(headers http.Header) map[string]string {
+	out := map[string]string{}
+	for k, values := range headers {
+		out[strings.ToLower(k)] = strings.Join(values, ", ")
+	}
+	return out
+}
+
+func stringField(m Frame, key string) string {
+	if s, ok := m[key].(string); ok {
+		return s
+	}
+	return ""
+}
+
+func intField(m Frame, key string, fallback int) int {
+	switch v := m[key].(type) {
+	case float64:
+		return int(v)
+	case int:
+		return v
+	default:
+		return fallback
+	}
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
diff --git a/internal/relay/dispatcher_test.go b/internal/relay/dispatcher_test.go
new file mode 100644
index 0000000..845ccf1
--- /dev/null
+++ b/internal/relay/dispatcher_test.go
@@ -0,0 +1,159 @@
+package relay
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+type testLogger struct{ t *testing.T }
+
+func (l testLogger) Info(msg string)  { l.t.Log("[INFO] " + msg) }
+func (l testLogger) Warn(msg string)  { l.t.Log("[WARN] " + msg) }
+func (l testLogger) Error(msg string) { l.t.Log("[ERROR] " + msg) }
+
+func TestClientDispatcherReqAndRequest(t *testing.T) {
+	local := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get(InternalHTTPHeader) != "1" {
+			t.Fatalf("missing internal relay header on %s", r.URL.Path)
+		}
+		if r.Header.Get(InternalClientLabelHeader) != "phone-a" {
+			t.Fatalf("missing client label on %s: %q", r.URL.Path, r.Header.Get(InternalClientLabelHeader))
+		}
+		if r.Header.Get("Authorization") != "Bearer gateway-token" {
+			t.Fatalf("missing loopback gateway token on %s", r.URL.Path)
+		}
+		switch r.URL.Path {
+		case "/gateway/notifications.push":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"ok":true,"data":{"ok":true,"echo":"notifications.push"}}`))
+		case "/notifications":
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"ok":true,"ingested":1}`))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer local.Close()
+
+	done := make(chan error, 1)
+	upgrader := websocket.Upgrader{}
+	relayServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Query().Get("apiKey") != "relay-key" {
+			t.Fatalf("unexpected apiKey query: %q", r.URL.Query().Get("apiKey"))
+		}
+		conn, err := upgrader.Upgrade(w, r, nil)
+		if err != nil {
+			done <- err
+			return
+		}
+		defer conn.Close()
+
+		if err := conn.WriteJSON(map[string]any{"type": "req", "id": "req_1", "method": "notifications.push", "params": map[string]any{"items": []any{}}}); err != nil {
+			done <- err
+			return
+		}
+		msg, err := readNonHeartbeat(conn)
+		if err != nil {
+			done <- err
+			return
+		}
+		wantPrefix := `{"type":"res","id":"req_1","ok":true,"payload":`
+		if !strings.HasPrefix(msg, wantPrefix) {
+			t.Fatalf("unexpected req response order/body: %s", msg)
+		}
+		var reqResp struct {
+			Type    string         `json:"type"`
+			ID      string         `json:"id"`
+			OK      bool           `json:"ok"`
+			Payload map[string]any `json:"payload"`
+		}
+		if err := json.Unmarshal([]byte(msg), &reqResp); err != nil {
+			done <- err
+			return
+		}
+		if reqResp.Payload["echo"] != "notifications.push" {
+			t.Fatalf("unexpected req payload: %+v", reqResp.Payload)
+		}
+
+		if err := conn.WriteJSON(map[string]any{
+			"type": "request", "id": "http_1", "method": "POST", "path": "/api/message/messageBridge/send",
+			"headers": map[string]string{"authorization": "Bearer external"}, "body": `{"notifications":[]}`,
+		}); err != nil {
+			done <- err
+			return
+		}
+		msg, err = readNonHeartbeat(conn)
+		if err != nil {
+			done <- err
+			return
+		}
+		wantPrefix = `{"type":"proxy_response","id":"http_1","status":200,`
+		if !strings.HasPrefix(msg, wantPrefix) {
+			t.Fatalf("unexpected proxy response order/body: %s", msg)
+		}
+		var httpResp struct {
+			Type   string `json:"type"`
+			ID     string `json:"id"`
+			Status int    `json:"status"`
+			Body   string `json:"body"`
+		}
+		if err := json.Unmarshal([]byte(msg), &httpResp); err != nil {
+			done <- err
+			return
+		}
+		if !strings.Contains(httpResp.Body, `"ingested":1`) {
+			t.Fatalf("unexpected proxy body: %s", httpResp.Body)
+		}
+		done <- nil
+	}))
+	defer relayServer.Close()
+
+	client := NewClient(ClientOptions{
+		TunnelURL:          "ws" + strings.TrimPrefix(relayServer.URL, "http"),
+		CredentialProvider: func() (Credential, error) { return relayCredential("relay-key"), nil },
+		HeartbeatSec:       60,
+		ReconnectBackoffMs: 50,
+		Logger:             testLogger{t},
+	})
+	dispatcher := NewDispatcher(DispatcherOptions{
+		Client: client, HTTPBaseURL: local.URL, HTTPToken: "gateway-token", ClientLabel: "phone-a", Logger: testLogger{t},
+	})
+	dispatcher.Start()
+	client.Start()
+	defer client.Stop("test done")
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("relay dispatcher test timed out")
+	}
+}
+
+func readNonHeartbeat(conn *websocket.Conn) (string, error) {
+	for {
+		msgType, data, err := conn.ReadMessage()
+		if err != nil {
+			return "", err
+		}
+		if msgType != websocket.TextMessage {
+			continue
+		}
+		text := string(data)
+		if text == "ping" {
+			if err := conn.WriteMessage(websocket.TextMessage, []byte("pong")); err != nil {
+				return "", err
+			}
+			continue
+		}
+		return text, nil
+	}
+}
diff --git a/internal/relay/supervisor.go b/internal/relay/supervisor.go
new file mode 100644
index 0000000..c047511
--- /dev/null
+++ b/internal/relay/supervisor.go
@@ -0,0 +1,197 @@
+package relay
+
+import (
+	"path/filepath"
+	"sync"
+
+	"github.com/YoooClaw/cli/internal/creds"
+)
+
+// SupervisorOptions 是多隧道 supervisor 配置。
+type SupervisorOptions struct {
+	TunnelURL          string
+	HTTPBaseURL        string
+	HTTPToken          string
+	HeartbeatSec       int
+	ReconnectBackoffMs int
+	StateDir           string
+	Logger             Logger
+}
+
+type managedTunnel struct {
+	entry      creds.ApiKeyEntry
+	client     *Client
+	dispatcher *Dispatcher
+}
+
+// Supervisor 管理每个 api-key label 对应的一条 Relay 隧道。
+type Supervisor struct {
+	opts SupervisorOptions
+
+	mu           sync.Mutex
+	tunnels      map[string]*managedTunnel
+	defaultLabel string
+	mode         string
+}
+
+// NewSupervisor 构造 supervisor。
+func NewSupervisor(opts SupervisorOptions) *Supervisor {
+	return &Supervisor{opts: opts, tunnels: map[string]*managedTunnel{}}
+}
+
+// Apply 增量应用 CredentialSet。
+func (s *Supervisor) Apply(set creds.CredentialSet) ApplyResult {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	result := ApplyResult{}
+	next := map[string]creds.ApiKeyEntry{}
+	for _, entry := range set.Entries {
+		next[entry.Label] = entry
+	}
+	for label, managed := range s.tunnels {
+		nextEntry, ok := next[label]
+		if !ok {
+			managed.client.Stop("removed")
+			managed.dispatcher.Cleanup()
+			delete(s.tunnels, label)
+			result.Stopped = append(result.Stopped, label)
+			continue
+		}
+		if nextEntry.Key != managed.entry.Key {
+			managed.client.Stop("key-changed")
+			managed.dispatcher.Cleanup()
+			s.tunnels[label] = s.startLocked(nextEntry)
+			result.Restarted = append(result.Restarted, label)
+		} else {
+			managed.entry = nextEntry
+			result.Unchanged = append(result.Unchanged, label)
+		}
+	}
+	for _, entry := range set.Entries {
+		if _, ok := s.tunnels[entry.Label]; ok {
+			continue
+		}
+		s.tunnels[entry.Label] = s.startLocked(entry)
+		result.Started = append(result.Started, entry.Label)
+	}
+	s.mode = set.Mode
+	s.defaultLabel = ""
+	if set.DefaultEntry != nil {
+		s.defaultLabel = set.DefaultEntry.Label
+	}
+	return result
+}
+
+// StopAll 停止全部隧道。
+func (s *Supervisor) StopAll(reason string) {
+	s.mu.Lock()
+	tunnels := s.tunnels
+	s.tunnels = map[string]*managedTunnel{}
+	s.mu.Unlock()
+	for _, managed := range tunnels {
+		managed.client.Stop(reason)
+		managed.dispatcher.Cleanup()
+	}
+}
+
+// Reconnect 重启指定 label 或全部隧道。
+func (s *Supervisor) Reconnect(label string) (reconnected []string, missing string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	labels := []string{}
+	if label != "" {
+		labels = []string{label}
+	} else {
+		for item := range s.tunnels {
+			labels = append(labels, item)
+		}
+	}
+	for _, item := range labels {
+		managed := s.tunnels[item]
+		if managed == nil {
+			return reconnected, item
+		}
+		managed.client.Stop("manual-reconnect")
+		managed.dispatcher.Cleanup()
+		s.tunnels[item] = s.startLocked(managed.entry)
+		reconnected = append(reconnected, item)
+	}
+	return reconnected, ""
+}
+
+// PushEvent 给所有已管理隧道广播事件。
+func (s *Supervisor) PushEvent(event string, payload any) {
+	s.mu.Lock()
+	tunnels := make([]*managedTunnel, 0, len(s.tunnels))
+	for _, managed := range s.tunnels {
+		tunnels = append(tunnels, managed)
+	}
+	s.mu.Unlock()
+	for _, managed := range tunnels {
+		managed.dispatcher.PushEvent(event, payload)
+	}
+}
+
+// Status 返回所有隧道状态。
+func (s *Supervisor) Status() SupervisorStatus {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	out := SupervisorStatus{Mode: s.mode, DefaultLabel: s.defaultLabel}
+	for _, managed := range s.tunnels {
+		status := managed.client.Status()
+		out.Tunnels = append(out.Tunnels, TunnelStatus{
+			Label: managed.entry.Label, Default: managed.entry.Label == s.defaultLabel,
+			Connected: status.Connected, URL: status.URL, ReconnectAttempt: status.ReconnectAttempt,
+			LastDisconnectReason: status.LastDisconnectReason,
+		})
+	}
+	return out
+}
+
+// DefaultStatus 返回默认隧道状态，没有默认则返回第一条。
+func (s *Supervisor) DefaultStatus() *Status {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if managed := s.tunnels[s.defaultLabel]; managed != nil {
+		status := managed.client.Status()
+		return &status
+	}
+	for _, managed := range s.tunnels {
+		status := managed.client.Status()
+		return &status
+	}
+	return nil
+}
+
+func (s *Supervisor) startLocked(entry creds.ApiKeyEntry) *managedTunnel {
+	label := entry.Label
+	logger := prefixedLogger{Logger: s.opts.Logger, Prefix: "[tunnel:" + label + "] "}
+	client := NewClient(ClientOptions{
+		TunnelURL: s.opts.TunnelURL,
+		CredentialProvider: func() (Credential, error) {
+			return relayCredential(entry.Key), nil
+		},
+		HeartbeatSec:       s.opts.HeartbeatSec,
+		ReconnectBackoffMs: s.opts.ReconnectBackoffMs,
+		StatusFilePath:     filepath.Join(s.opts.StateDir, "state", "tunnels", label+".json"),
+		Logger:             logger,
+	})
+	dispatcher := NewDispatcher(DispatcherOptions{
+		Client: client, HTTPBaseURL: s.opts.HTTPBaseURL, HTTPToken: s.opts.HTTPToken,
+		ClientLabel: label, Logger: logger,
+	})
+	dispatcher.Start()
+	client.Start()
+	s.opts.Logger.Info("[tunnel:" + label + "] Relay tunnel started")
+	return &managedTunnel{entry: entry, client: client, dispatcher: dispatcher}
+}
+
+type prefixedLogger struct {
+	Logger
+	Prefix string
+}
+
+func (l prefixedLogger) Info(msg string)  { l.Logger.Info(l.Prefix + msg) }
+func (l prefixedLogger) Warn(msg string)  { l.Logger.Warn(l.Prefix + msg) }
+func (l prefixedLogger) Error(msg string) { l.Logger.Error(l.Prefix + msg) }
diff --git a/internal/relay/types.go b/internal/relay/types.go
new file mode 100644
index 0000000..8470071
--- /dev/null
+++ b/internal/relay/types.go
@@ -0,0 +1,122 @@
+package relay
+
+import "time"
+
+const (
+	// InternalHTTPHeader 标记 Relay loopback 请求，daemon 用它保留真实 client label。
+	InternalHTTPHeader = "x-openclaw-relay-internal"
+	// InternalClientLabelHeader 是当前隧道对应的 api-key label。
+	InternalClientLabelHeader = "x-yoooclaw-internal-client-label"
+)
+
+const (
+	defaultHeartbeatSec       = 10
+	defaultReconnectBackoffMs = 2000
+	handshakeTimeout          = 15 * time.Second
+	connectWatchdog           = 20 * time.Second
+)
+
+// Logger 是 relay 包依赖的最小日志接口。
+type Logger interface {
+	Info(string)
+	Warn(string)
+	Error(string)
+}
+
+// Frame 是 Relay JSON frame。
+type Frame map[string]any
+
+// RPCResponseFrame 是 Gateway RPC 响应帧：{type,id,ok,payload?,error?}。
+type RPCResponseFrame struct {
+	Type    string `json:"type"`
+	ID      string `json:"id"`
+	OK      bool   `json:"ok"`
+	Payload any    `json:"payload,omitempty"`
+	Error   any    `json:"error,omitempty"`
+}
+
+// ProxyResponseFrame 是 HTTP 代理响应帧。
+type ProxyResponseFrame struct {
+	Type    string            `json:"type"`
+	ID      string            `json:"id"`
+	Status  int               `json:"status"`
+	Headers map[string]string `json:"headers"`
+	Body    string            `json:"body,omitempty"`
+}
+
+// StreamFrame 是流式响应片段帧。
+type StreamFrame struct {
+	Type  string `json:"type"`
+	ID    string `json:"id"`
+	State string `json:"state"`
+	Data  string `json:"data"`
+}
+
+// ProxyErrorFrame 是 HTTP 代理错误帧。
+type ProxyErrorFrame struct {
+	Type    string `json:"type"`
+	ID      string `json:"id"`
+	Status  int    `json:"status"`
+	Message string `json:"message"`
+}
+
+// WSOpenedFrame 是 WS 子通道打开确认。
+type WSOpenedFrame struct {
+	Type string `json:"type"`
+	ID   string `json:"id"`
+}
+
+// WSDataFrame 是 WS 子通道数据帧。
+type WSDataFrame struct {
+	Type string `json:"type"`
+	ID   string `json:"id"`
+	Data string `json:"data"`
+}
+
+// WSCloseFrame 是 WS 子通道关闭帧。
+type WSCloseFrame struct {
+	Type   string `json:"type"`
+	ID     string `json:"id"`
+	Code   int    `json:"code,omitempty"`
+	Reason string `json:"reason,omitempty"`
+}
+
+// EventFrame 是 daemon 主动推送事件帧。
+type EventFrame struct {
+	Type    string `json:"type"`
+	Event   string `json:"event"`
+	Payload any    `json:"payload"`
+}
+
+// Status 是单条隧道状态。
+type Status struct {
+	Connected            bool
+	URL                  string
+	ReconnectAttempt     int
+	LastDisconnectReason string
+}
+
+// TunnelStatus 是 supervisor 对外暴露的单隧道状态。
+type TunnelStatus struct {
+	Label                string `json:"label"`
+	Default              bool   `json:"default"`
+	Connected            bool   `json:"connected"`
+	URL                  string `json:"url"`
+	ReconnectAttempt     int    `json:"reconnectAttempt"`
+	LastDisconnectReason string `json:"lastDisconnectReason,omitempty"`
+}
+
+// SupervisorStatus 是全部隧道状态。
+type SupervisorStatus struct {
+	Mode         string         `json:"mode"`
+	DefaultLabel string         `json:"defaultLabel"`
+	Tunnels      []TunnelStatus `json:"tunnels"`
+}
+
+// ApplyResult 是 credential set 增量应用结果。
+type ApplyResult struct {
+	Started   []string `json:"started"`
+	Stopped   []string `json:"stopped"`
+	Restarted []string `json:"restarted"`
+	Unchanged []string `json:"unchanged"`
+}

From e4f7d87a94a2cf92d8fbccb24397286f2fdbb376 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 19:12:11 +0800
Subject: [PATCH 09/13] chore(release): prepare 0.2.0-beta.0 Go beta

---
 .github/workflows/release-cli.yml | 409 +++++++++++++-----------------
 package.json                      |   2 +-
 2 files changed, 175 insertions(+), 236 deletions(-)

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index bd63c36..5ee2ed2 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -27,94 +27,54 @@ jobs:
           echo "::notice::Release source branch(es):"
           echo "$CONTAINING_RELEASE_BRANCHES"
 
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
       - uses: actions/setup-node@v4
         with:
           node-version: 22
 
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
       - name: Verify tag version
         run: |
-          PKG_VERSION="$(jq -r .version package.json)"
+          PKG_VERSION="$(node -p "require('./package.json').version")"
           TAG_VERSION="${GITHUB_REF_NAME#cli-v}"
           if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
             echo "::error::tag $TAG_VERSION 与 package.json $PKG_VERSION 不一致"
             exit 1
           fi
 
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Verify CLI source
+      - name: Verify Go source
         run: |
-          bun run typecheck
-          bun run test
-
-      - run: bun run build
-        env:
-          LIGHT_APP_KEY: ${{ secrets.LIGHT_APP_KEY }}
-          LIGHT_TEMPLATE_ID: ${{ secrets.LIGHT_TEMPLATE_ID }}
+          go test ./...
+          go vet ./...
 
-      - name: Smoke test npm CLI build
-        run: |
-          test -s dist/bin.cjs
-          test -s dist/index.cjs
-          test -s dist/index.d.ts
-
-          VERSION_OUT="$(node dist/bin.cjs --version)"
-          if [ "$VERSION_OUT" != "$(jq -r .version package.json)" ]; then
-            echo "::error::dist/bin.cjs --version 输出 $VERSION_OUT，与 package.json 不一致"
-            exit 1
-          fi
-
-          node dist/bin.cjs --help > /tmp/yoooclaw-help.txt
-          grep -q "Usage:" /tmp/yoooclaw-help.txt
-          grep -q "yoooclaw" /tmp/yoooclaw-help.txt
-
-  build-native-linux:
+  build-release:
     needs: preflight
-    runs-on: ubuntu-latest
+    runs-on: macos-latest
+    environment: production
     steps:
       - uses: actions/checkout@v4
 
-      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
         with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Build Linux native binaries
-        run: bun scripts/build-native.ts --target linux-x64,linux-arm64
-        env:
-          LIGHT_APP_KEY: ${{ secrets.LIGHT_APP_KEY }}
-          LIGHT_TEMPLATE_ID: ${{ secrets.LIGHT_TEMPLATE_ID }}
-
-      - name: Smoke test Linux native binary
-        run: ./dist-native/yoooclaw-linux-x64 --version
+          node-version: 22
 
-      - name: Upload Linux native binaries
-        uses: actions/upload-artifact@v7
+      - uses: actions/setup-go@v5
         with:
-          name: cli-native-linux
-          path: |
-            dist-native/yoooclaw-linux-x64
-            dist-native/yoooclaw-linux-arm64
-          if-no-files-found: error
-          compression-level: 0
-
-  build-native-darwin:
-    needs: preflight
-    runs-on: macos-latest
-    environment: production
-    steps:
-      - uses: actions/checkout@v4
+          go-version-file: go.mod
+          cache: true
 
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+      - name: Resolve version
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          TAG_VERSION="${GITHUB_REF_NAME#cli-v}"
+          if [ "$VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::tag $TAG_VERSION 与 package.json $VERSION 不一致"
+            exit 1
+          fi
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
 
       - name: Validate Apple signing secrets
         env:
@@ -141,14 +101,24 @@ jobs:
             exit 1
           fi
 
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
+      - name: Build Go npm distribution
+        run: scripts/build-go.sh "$VERSION"
 
-      - name: Build Darwin native binaries
-        run: bun scripts/build-native.ts --target darwin-arm64,darwin-x64
-        env:
-          LIGHT_APP_KEY: ${{ secrets.LIGHT_APP_KEY }}
-          LIGHT_TEMPLATE_ID: ${{ secrets.LIGHT_TEMPLATE_ID }}
+      - name: Smoke test current macOS binary
+        run: |
+          case "$(uname -m)" in
+            arm64) bin="dist-native/yoooclaw-darwin-arm64" ;;
+            x86_64) bin="dist-native/yoooclaw-darwin-x64" ;;
+            *)
+              echo "::error::Unsupported macOS runner arch: $(uname -m)"
+              exit 1
+              ;;
+          esac
+          VERSION_OUT="$("$bin" --version)"
+          if [ "$VERSION_OUT" != "$VERSION" ]; then
+            echo "::error::$bin --version 输出 $VERSION_OUT，期望 $VERSION"
+            exit 1
+          fi
 
       - name: Import Developer ID certificate
         env:
@@ -187,7 +157,7 @@ jobs:
 
           echo "SIGNING_IDENTITY=$SIGNING_IDENTITY" >> "$GITHUB_ENV"
 
-      - name: Sign Darwin native binaries
+      - name: Sign Darwin binaries
         run: |
           for file in \
             dist-native/yoooclaw-darwin-arm64 \
@@ -203,7 +173,18 @@ jobs:
             codesign --verify --strict --verbose=2 "$file"
           done
 
-      - name: Notarize Darwin native binaries
+          cp dist-native/yoooclaw-darwin-arm64 dist-npm/cli-darwin-arm64/bin/yc
+          cp dist-native/yoooclaw-darwin-x64 dist-npm/cli-darwin-x64/bin/yc
+          chmod +x dist-npm/cli-darwin-arm64/bin/yc dist-npm/cli-darwin-x64/bin/yc
+
+          for file in \
+            dist-npm/cli-darwin-arm64/bin/yc \
+            dist-npm/cli-darwin-x64/bin/yc
+          do
+            codesign --verify --strict --verbose=2 "$file"
+          done
+
+      - name: Notarize Darwin binaries
         env:
           APPLE_NOTARY_APPLE_ID: ${{ secrets.APPLE_NOTARY_APPLE_ID }}
           APPLE_NOTARY_TEAM_ID: ${{ secrets.APPLE_NOTARY_TEAM_ID }}
@@ -249,15 +230,54 @@ jobs:
             exit 1
           fi
 
-          # Apple 会为 ZIP 内的独立二进制发布在线 ticket；独立二进制本身无法 staple。
+      - name: Verify npm package layout
+        run: |
+          node <<'NODE'
+          const fs = require('node:fs');
+          const path = require('node:path');
+          const version = process.env.VERSION;
+          const root = 'dist-npm';
+          const dirs = fs.readdirSync(root).sort();
+          const expected = [
+            'cli',
+            'cli-darwin-arm64',
+            'cli-darwin-x64',
+            'cli-linux-arm64',
+            'cli-linux-x64',
+            'cli-win32-x64',
+          ];
+          for (const dir of expected) {
+            if (!dirs.includes(dir)) throw new Error(`missing ${dir}`);
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, dir, 'package.json'), 'utf8'));
+            if (pkg.version !== version) throw new Error(`${pkg.name} version ${pkg.version} != ${version}`);
+          }
+          const main = JSON.parse(fs.readFileSync(path.join(root, 'cli', 'package.json'), 'utf8'));
+          for (const dep of [
+            '@yoooclaw/cli-darwin-arm64',
+            '@yoooclaw/cli-darwin-x64',
+            '@yoooclaw/cli-linux-arm64',
+            '@yoooclaw/cli-linux-x64',
+            '@yoooclaw/cli-win32-x64',
+          ]) {
+            if (main.optionalDependencies?.[dep] !== version) {
+              throw new Error(`optional dependency ${dep} is not pinned to ${version}`);
+            }
+          }
+          NODE
+
+      - name: Upload native binaries
+        uses: actions/upload-artifact@v4
+        with:
+          name: cli-native
+          path: dist-native/
+          if-no-files-found: error
+          compression-level: 0
 
-      - name: Upload signed and notarized Darwin native binaries
-        uses: actions/upload-artifact@v7
+      - name: Upload npm packages
+        uses: actions/upload-artifact@v4
         with:
-          name: cli-native-darwin
-          path: |
-            dist-native/yoooclaw-darwin-arm64
-            dist-native/yoooclaw-darwin-x64
+          name: cli-npm
+          path: dist-npm/
           if-no-files-found: error
           compression-level: 0
 
@@ -269,209 +289,129 @@ jobs:
           fi
 
   release:
-    needs:
-      - preflight
-      - build-native-linux
-      - build-native-darwin
+    needs: build-release
     runs-on: ubuntu-latest
     environment: production
-    # job 级注入：覆盖显式 build 与 `bun publish` 触发的 prepublishOnly 重建，
-    # 否则 publish 期间的重建会因缺 env 把灯效凭据烤成空串。
-    env:
-      LIGHT_APP_KEY: ${{ secrets.LIGHT_APP_KEY }}
-      LIGHT_TEMPLATE_ID: ${{ secrets.LIGHT_TEMPLATE_ID }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Ensure tag commit is on release branch
-        run: |
-          git fetch --no-tags origin '+refs/heads/release/*:refs/remotes/origin/release/*'
-          CONTAINING_RELEASE_BRANCHES="$(git branch -r --contains "$GITHUB_SHA" --list 'origin/release/*')"
-          if [ -z "$CONTAINING_RELEASE_BRANCHES" ]; then
-            echo "::error::Release tag must point to a commit on origin/release/**"
-            exit 1
-          fi
-          echo "::notice::Release source branch(es):"
-          echo "$CONTAINING_RELEASE_BRANCHES"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
 
-      - uses: oven-sh/setup-bun@v2
+      - name: Download native binaries
+        uses: actions/download-artifact@v4
         with:
-          bun-version: latest
+          name: cli-native
+          path: dist-native
 
-      - uses: actions/setup-node@v4
+      - name: Download npm packages
+        uses: actions/download-artifact@v4
         with:
-          node-version: 22
+          name: cli-npm
+          path: dist-npm
 
-      - name: Resolve version & channel
+      - name: Resolve version and channel
         run: |
-          PKG_VERSION="$(jq -r .version package.json)"
+          VERSION="$(node -p "require('./package.json').version")"
           TAG_VERSION="${GITHUB_REF_NAME#cli-v}"
-          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
-            echo "::error::tag $TAG_VERSION 与 package.json $PKG_VERSION 不一致"
+          if [ "$VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::tag $TAG_VERSION 与 package.json $VERSION 不一致"
             exit 1
           fi
-          echo "VERSION=$PKG_VERSION" >> "$GITHUB_ENV"
-          if [[ "$PKG_VERSION" == *-* ]]; then
-            echo "IS_BETA=1" >> "$GITHUB_ENV"
-            echo "::notice::预发布版本 cli-v$PKG_VERSION（仅 GitHub Release，跳过 npm publish）"
+
+          echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+          if [[ "$VERSION" == *-* ]]; then
+            echo "NPM_TAG=beta" >> "$GITHUB_ENV"
+            echo "PRERELEASE=1" >> "$GITHUB_ENV"
           else
-            echo "IS_BETA=0" >> "$GITHUB_ENV"
-            echo "::notice::稳定版本 cli-v$PKG_VERSION（GitHub Release + npm）"
+            echo "NPM_TAG=latest" >> "$GITHUB_ENV"
+            echo "PRERELEASE=0" >> "$GITHUB_ENV"
           fi
 
-      - name: Verify stable release prerequisites
-        if: env.IS_BETA == '0'
+      - name: Verify npm token
         env:
-          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          if [ -z "$NPM_CONFIG_TOKEN" ]; then
-            echo "::error::稳定版发布需要配置 NPM_TOKEN"
-            exit 1
-          fi
-
-          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::error::稳定版版本号必须是 x.y.z，当前为 $VERSION"
-            exit 1
-          fi
-
-          if NPM_VIEW_OUTPUT=$(npm view "@yoooclaw/cli@$VERSION" version 2>&1); then
-            echo "NPM_PACKAGE_EXISTS=1" >> "$GITHUB_ENV"
-            echo "::notice::@yoooclaw/cli@$VERSION 已存在于 npm，跳过重复发布"
-          elif ! grep -Eq '(^npm ERR! code E404|404)' <<< "$NPM_VIEW_OUTPUT"; then
-            echo "::error::无法确认 @yoooclaw/cli@$VERSION 是否已存在于 npm"
-            echo "$NPM_VIEW_OUTPUT"
+          if [ -z "$NODE_AUTH_TOKEN" ]; then
+            echo "::error::发布 npm 需要配置 NPM_TOKEN"
             exit 1
-          else
-            echo "NPM_PACKAGE_EXISTS=0" >> "$GITHUB_ENV"
           fi
 
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - run: bun run build
-
-      - name: Smoke test npm CLI build
+      - name: Smoke test Linux binary
         run: |
-          test -s dist/bin.cjs
-          test -s dist/index.cjs
-          test -s dist/index.d.ts
-
-          VERSION_OUT="$(node dist/bin.cjs --version)"
+          chmod +x dist-native/yoooclaw-*
+          VERSION_OUT="$(./dist-native/yoooclaw-linux-x64 --version)"
           if [ "$VERSION_OUT" != "$VERSION" ]; then
-            echo "::error::dist/bin.cjs --version 输出 $VERSION_OUT，期望 $VERSION"
+            echo "::error::linux native --version 输出 $VERSION_OUT，期望 $VERSION"
             exit 1
           fi
 
-          node dist/bin.cjs --help > /tmp/yoooclaw-help.txt
-          grep -q "Usage:" /tmp/yoooclaw-help.txt
-          grep -q "yoooclaw" /tmp/yoooclaw-help.txt
-
-      - name: Download native binaries
-        uses: actions/download-artifact@v8
-        with:
-          pattern: cli-native-*
-          path: dist-native
-          merge-multiple: true
+      - name: Pack npm tarballs
+        run: |
+          mkdir -p release-tarballs
+          for dir in dist-npm/cli-* dist-npm/cli; do
+            npm pack "$dir" --pack-destination release-tarballs --json
+          done
 
-      - name: Smoke test native binaries
+      - name: Publish npm packages
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          required=(
-            dist-native/yoooclaw-darwin-arm64
-            dist-native/yoooclaw-darwin-x64
-            dist-native/yoooclaw-linux-x64
-            dist-native/yoooclaw-linux-arm64
-          )
-          for file in "${required[@]}"; do
-            if [ ! -s "$file" ]; then
-              echo "::error::缺少 native 产物: $file"
-              exit 1
+          publish_pkg() {
+            local dir="$1"
+            local name
+            local version
+            name="$(node -p "require('./${dir}/package.json').name")"
+            version="$(node -p "require('./${dir}/package.json').version")"
+
+            if npm view "$name@$version" version >/dev/null 2>&1; then
+              echo "::notice::$name@$version 已存在，跳过"
+              return
             fi
-          done
 
-          chmod +x dist-native/yoooclaw-*
-          VERSION_OUT="$(./dist-native/yoooclaw-linux-x64 --version)"
-          if [ "$VERSION_OUT" != "$VERSION" ]; then
-            echo "::error::native --version 输出 $VERSION_OUT，期望 $VERSION"
-            exit 1
-          fi
+            echo "::notice::发布 $name@$version --tag $NPM_TAG"
+            npm publish "$dir" --access public --tag "$NPM_TAG"
+          }
+
+          for dir in dist-npm/cli-*; do
+            publish_pkg "$dir"
+          done
+          publish_pkg dist-npm/cli
 
-      - name: Compute checksums for native binaries
+      - name: Compute checksums
         run: |
           cd dist-native
           sha256sum yoooclaw-* > checksums.txt
-          if [ "$(wc -l < checksums.txt | tr -d ' ')" != "4" ]; then
-            echo "::error::checksums.txt 应包含 4 个 native 产物"
+          expected=5
+          actual="$(wc -l < checksums.txt | tr -d ' ')"
+          if [ "$actual" != "$expected" ]; then
+            echo "::error::checksums.txt 应包含 $expected 个 native 产物，实际为 $actual"
             exit 1
           fi
           cat checksums.txt
 
-      - run: |
-          rm -f ./*.tgz
-          bun pm pack
-
-      - name: Verify npm package artifact
-        run: |
-          shopt -s nullglob
-          tarballs=(./*.tgz)
-          if [ "${#tarballs[@]}" -ne 1 ]; then
-            echo "::error::期望生成 1 个 npm tarball，实际为 ${#tarballs[@]}"
-            printf '%s\n' "${tarballs[@]}"
-            exit 1
-          fi
-
-          tar -tzf "${tarballs[0]}" > /tmp/yoooclaw-tarball.txt
-          required=(
-            package/package.json
-            package/dist/bin.cjs
-            package/dist/index.cjs
-            package/dist/index.d.ts
-            package/skills/yoooclaw-notification-query/SKILL.md
-            package/skills/yoooclaw-lightrule-create/SKILL.md
-            package/skills/yoooclaw-tunnel-debug/SKILL.md
-          )
-          for path in "${required[@]}"; do
-            if ! grep -qx "$path" /tmp/yoooclaw-tarball.txt; then
-              echo "::error::npm tarball 缺少 $path"
-              exit 1
-            fi
-          done
-
-      - name: Publish to npm
-        if: env.IS_BETA == '0' && env.NPM_PACKAGE_EXISTS == '0'
-        run: bun publish --access public
-        env:
-          NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Repack npm tarball for GitHub Release
-        run: |
-          rm -f ./*.tgz
-          bun pm pack
-
       - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          shopt -s nullglob
-          tarballs=(./*.tgz)
-          if [ "${#tarballs[@]}" -ne 1 ]; then
-            echo "::error::GitHub Release 需要 1 个 npm tarball，实际为 ${#tarballs[@]}"
-            exit 1
+          args=(--generate-notes)
+          if [ "$PRERELEASE" = "1" ]; then
+            args+=(--prerelease)
           fi
 
-          ARGS=(--generate-notes)
-          if [ "$IS_BETA" = "1" ]; then
-            ARGS+=(--prerelease)
-          fi
           gh release create "cli-v$VERSION" \
-            "${tarballs[0]}" \
             dist-native/yoooclaw-darwin-arm64 \
             dist-native/yoooclaw-darwin-x64 \
-            dist-native/yoooclaw-linux-x64 \
             dist-native/yoooclaw-linux-arm64 \
+            dist-native/yoooclaw-linux-x64 \
+            dist-native/yoooclaw-win32-x64.exe \
             dist-native/checksums.txt \
-            "${ARGS[@]}"
+            release-tarballs/*.tgz \
+            "${args[@]}"
 
       - name: Notify Feishu
         if: success()
@@ -489,7 +429,6 @@ jobs:
             LOG_ARGS=(-20 "$CURRENT_TAG")
           fi
 
-          # 逐条输出：标题 + 缩进的提交正文（跳过 merge 与版本号提交）
           CHANGES=$(git log --no-merges --pretty=format:'%H' "${LOG_ARGS[@]}" | while read -r h; do
             subj=$(git log -1 --pretty=format:'%s' "$h")
             if grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-.].*)?$' <<< "$subj"; then
@@ -505,7 +444,7 @@ jobs:
 
           URL="https://github.com/${GITHUB_REPOSITORY}/releases/tag/${CURRENT_TAG}"
           CHANNEL="稳定版"
-          [ "$IS_BETA" = "1" ] && CHANNEL="预发布"
+          [ "$PRERELEASE" = "1" ] && CHANNEL="预发布"
 
           TEXT="🚀 @yoooclaw/cli ${CURRENT_TAG}（${CHANNEL}）已发布
 
diff --git a/package.json b/package.json
index cea9319..4361c7b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yoooclaw/cli",
-  "version": "0.1.9",
+  "version": "0.2.0-beta.0",
   "type": "module",
   "description": "yoooclaw 独立 CLI：本地守护进程接收手机通知、Relay 隧道、灯效规则评估，Agent-Native",
   "bin": {

From fc81de3ce65ae82de04342ba0e76a75cd8c46e08 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 19:16:10 +0800
Subject: [PATCH 10/13] fix(release): pack Go npm packages from local paths

---
 .github/workflows/release-cli.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index 5ee2ed2..1139b46 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -354,7 +354,7 @@ jobs:
         run: |
           mkdir -p release-tarballs
           for dir in dist-npm/cli-* dist-npm/cli; do
-            npm pack "$dir" --pack-destination release-tarballs --json
+            npm pack "./$dir" --pack-destination release-tarballs --json
           done
 
       - name: Publish npm packages
@@ -374,7 +374,7 @@ jobs:
             fi
 
             echo "::notice::发布 $name@$version --tag $NPM_TAG"
-            npm publish "$dir" --access public --tag "$NPM_TAG"
+            npm publish "./$dir" --access public --tag "$NPM_TAG"
           }
 
           for dir in dist-npm/cli-*; do

From 47913dbac5acb484ca438865d1f3a9693550b81f Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 19:21:55 +0800
Subject: [PATCH 11/13] fix(release): make platform packages public on retry

---
 .github/workflows/release-cli.yml | 23 +++++++++++++++--------
 scripts/gen-pkg.mjs               |  2 +-
 2 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index 1139b46..6f329cf 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -370,11 +370,13 @@ jobs:
 
             if npm view "$name@$version" version >/dev/null 2>&1; then
               echo "::notice::$name@$version 已存在，跳过"
+              npm access public "$name"
               return
             fi
 
             echo "::notice::发布 $name@$version --tag $NPM_TAG"
             npm publish "./$dir" --access public --tag "$NPM_TAG"
+            npm access public "$name"
           }
 
           for dir in dist-npm/cli-*; do
@@ -398,20 +400,25 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          args=(--generate-notes)
-          if [ "$PRERELEASE" = "1" ]; then
-            args+=(--prerelease)
-          fi
-
-          gh release create "cli-v$VERSION" \
+          assets=(
             dist-native/yoooclaw-darwin-arm64 \
             dist-native/yoooclaw-darwin-x64 \
             dist-native/yoooclaw-linux-arm64 \
             dist-native/yoooclaw-linux-x64 \
             dist-native/yoooclaw-win32-x64.exe \
             dist-native/checksums.txt \
-            release-tarballs/*.tgz \
-            "${args[@]}"
+            release-tarballs/*.tgz
+          )
+
+          if gh release view "cli-v$VERSION" >/dev/null 2>&1; then
+            gh release upload "cli-v$VERSION" "${assets[@]}" --clobber
+          else
+            args=(--generate-notes)
+            if [ "$PRERELEASE" = "1" ]; then
+              args+=(--prerelease)
+            fi
+            gh release create "cli-v$VERSION" "${assets[@]}" "${args[@]}"
+          fi
 
       - name: Notify Feishu
         if: success()
diff --git a/scripts/gen-pkg.mjs b/scripts/gen-pkg.mjs
index b6389af..0027e35 100644
--- a/scripts/gen-pkg.mjs
+++ b/scripts/gen-pkg.mjs
@@ -13,7 +13,7 @@ const COMMON = {
   version,
   license: "MIT",
   author: "developer@yoooclaw.com",
-  repository: { type: "git", url: "https://github.com/YoooClaw/cli.git" },
+  repository: { type: "git", url: "git+https://github.com/YoooClaw/cli.git" },
   publishConfig: { access: "public" },
 };
 

From 5a3cb1a0279b278545ff7c212efb5935debc9b1c Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 19:24:42 +0800
Subject: [PATCH 12/13] fix(release): use npm access status syntax

---
 .github/workflows/release-cli.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index 6f329cf..e1b8556 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -370,13 +370,13 @@ jobs:
 
             if npm view "$name@$version" version >/dev/null 2>&1; then
               echo "::notice::$name@$version 已存在，跳过"
-              npm access public "$name"
+              npm access set status=public "$name"
               return
             fi
 
             echo "::notice::发布 $name@$version --tag $NPM_TAG"
             npm publish "./$dir" --access public --tag "$NPM_TAG"
-            npm access public "$name"
+            npm access set status=public "$name"
           }
 
           for dir in dist-npm/cli-*; do

From 7bc2759d5040a036ece501eb7cf2a88d996a4010 Mon Sep 17 00:00:00 2001
From: chengkebin <chengkebin>
Date: Sat, 6 Jun 2026 19:29:11 +0800
Subject: [PATCH 13/13] fix(release): preserve native executable mode

---
 .github/workflows/release-cli.yml | 8 ++++++++
 npm/cli/bin/yc.js                 | 9 +++++++++
 package.json                      | 2 +-
 scripts/gen-pkg.mjs               | 3 +++
 4 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
index e1b8556..1fb48e9 100644
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -384,6 +384,14 @@ jobs:
           done
           publish_pkg dist-npm/cli
 
+      - name: Deprecate broken beta.0
+        if: env.VERSION == '0.2.0-beta.1'
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          message="@yoooclaw/cli 0.2.0-beta.0 的平台二进制缺少 executable bit，请升级到 0.2.0-beta.1。"
+          npm deprecate "@yoooclaw/cli@0.2.0-beta.0" "$message"
+
       - name: Compute checksums
         run: |
           cd dist-native
diff --git a/npm/cli/bin/yc.js b/npm/cli/bin/yc.js
index 5720770..3f9bc44 100644
--- a/npm/cli/bin/yc.js
+++ b/npm/cli/bin/yc.js
@@ -8,6 +8,7 @@
 // 设计与 esbuild / turbo 一致：主包不含二进制，只含这个极薄 launcher。
 
 const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
 
 function resolveBinary() {
   const platform = process.platform; // darwin | linux | win32
@@ -34,6 +35,14 @@ if (!bin) {
   process.exit(1);
 }
 
+if (process.platform !== "win32") {
+  try {
+    fs.chmodSync(bin, 0o755);
+  } catch {
+    // Best effort only: spawnSync will surface the real error if execution still fails.
+  }
+}
+
 const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
 if (result.error) {
   process.stderr.write(`@yoooclaw/cli: 启动二进制失败：${result.error.message}\n`);
diff --git a/package.json b/package.json
index 4361c7b..eed357d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@yoooclaw/cli",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.1",
   "type": "module",
   "description": "yoooclaw 独立 CLI：本地守护进程接收手机通知、Relay 隧道、灯效规则评估，Agent-Native",
   "bin": {
diff --git a/scripts/gen-pkg.mjs b/scripts/gen-pkg.mjs
index 0027e35..0fe8028 100644
--- a/scripts/gen-pkg.mjs
+++ b/scripts/gen-pkg.mjs
@@ -30,6 +30,9 @@ if (mode === "platform") {
     // os/cpu 让 npm 只在匹配平台安装本子包；files 限定只发布二进制。
     os: [npmOs],
     cpu: [npmCpu],
+    // npm only preserves executable mode reliably for files declared as bins.
+    // Use a non-primary name so the launcher package keeps owning yc/yoooclaw.
+    bin: { "yc-native": `bin/${binName}` },
     files: [`bin/${binName}`],
   });
 } else if (mode === "main") {