magic-agent 1.0.3 → 1.0.49

package/cmd/magic-client/clientctl.go

@@ -0,0 +1,273 @@
+package main
+
+// clientctl.go - `magic-client start|stop|status`：把服务本身当后台常驻进程管起来。
+//
+// 为什么在插件侧而不是 core：`internal/boundary` 钉着「core 的依赖闭包里不许出现
+// internal/client」（桌面 / 移动端是可选插件）。core 的 `magic-agent client …`
+// 只负责转发到这里。
+//
+// 三件事都围绕同一份状态文件（默认 ~/.magic-client/client.json，0600）：
+//   start  后台拉起 serve，等它报端口，落状态
+//   status 读状态 + 探活
+//   stop   SIGTERM（5s 不退再 SIGKILL），清状态
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/darren/magic-agent/internal/client"
+)
+
+// newFlagSet 建一个带中文用法头的 flag 集。
+//
+// 用标准库 flag 而不是 cobra：magic-client 是个小工具，多一层命令框架只会让
+// 「参数原样透传」这件事变复杂（core 那边已经不解析，这里要能接住任意 flag）。
+func newFlagSet(name string) *flag.FlagSet {
+	fs := flag.NewFlagSet(name, flag.ExitOnError)
+	fs.Usage = func() {
+		fmt.Fprintf(os.Stderr, "用法: magic-client %s [flags]\n\n", name)
+		fs.PrintDefaults()
+	}
+	return fs
+}
+
+func isDirPath(p string) bool {
+	st, err := os.Stat(p)
+	return err == nil && st.IsDir()
+}
+
+func writeJSONStdout(v any) {
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetIndent("", "  ")
+	_ = enc.Encode(v)
+}
+
+// runClientCommand 处理 start / stop / status；未知动作返回 false 交给 serve 分支。
+func runClientCommand(action string, args []string) (handled bool, code int) {
+	switch action {
+	case "start":
+		return true, runClientStart(args)
+	case "stop":
+		return true, runClientStop(args)
+	case "status":
+		return true, runClientStatus(args)
+	}
+	return false, 0
+}
+
+// runClientCommandWithExit 同上，但保证「动作认了、退出码一定有值」。
+func runClientCommandWithExit(action string, args []string) int {
+	handled, code := runClientCommand(action, args)
+	if !handled {
+		fmt.Fprintf(os.Stderr, "magic-client: 未知动作 %q\n\n%s", action, clientUsage)
+		return 2
+	}
+	return code
+}
+
+const clientUsage = `magic-client - magic-agent 的客户端插件（桌面 / 移动端界面 + 扩展接口）
+
+用法：
+  magic-client serve  [flags]     前台运行（看日志 / 排障用）
+  magic-client start  [flags]     后台常驻（关掉终端也还在），打印手机可用的地址
+  magic-client status [--json]    看状态（是否在跑、端口、手机地址、健康检查）
+  magic-client stop               停掉后台实例（本来没跑也算成功）
+
+手机要连**必须**用 start --lan（或 serve --lan）：默认只绑 127.0.0.1，同机可用、手机不可达。
+--lan 时令牌是唯一门锁，至少 24 字符；start 会复用 ~/.magic-client/token，跨重启稳定
+（手机里存的是「地址 + 令牌」，每次换就等于配对作废）。
+
+serve 的 flags 见 ` + "`magic-client serve --help`" + `；start 另有 --state / --log / --wait。
+`
+
+func runClientStart(args []string) int {
+	fs := newFlagSet("start")
+	lan := fs.Bool("lan", false, "绑到局域网（0.0.0.0），让手机 / 平板连得上。⚠️ 开了之后令牌是唯一门锁")
+	addr := fs.String("addr", "", "监听地址（默认：带 --lan 时 0.0.0.0:0，否则 127.0.0.1:0）")
+	profilePath := fs.String("profile", "", "profile JSON 路径（空 = 内置默认）")
+	uiDir := fs.String("ui-dir", "", "桌面端界面目录（空 = 自动找与本程序同级的 client-ui）")
+	mobileDir := fs.String("mobile-dir", "", "移动端界面目录（空 = 自动找同级的 client-ui-mobile），/m/ 由它提供")
+	proxyAddr := fs.String("proxy-addr", "", "SOCKS5 出口监听地址（移动端 VPN 隧道核心用），如 0.0.0.0:1080")
+	token := fs.String("token", "", "访问令牌（空 = 复用 ~/.magic-client/token，没有就生成；--lan 时至少 24 字符）")
+	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json；也可用 MAGIC_CLIENT_STATE）")
+	logPath := fs.String("log", "", "后台日志路径（默认 ~/.magic-client/logs/client.log；也可用 MAGIC_CLIENT_LOG）")
+	wait := fs.Duration("wait", 15*time.Second, "等后台服务报端口的时长（超时即判定启动失败）")
+	browseUA := fs.String("browse-ua", "", "内置浏览器中转的 User-Agent：mobile（默认）/ desktop / 自定义")
+	_ = fs.Parse(args)
+
+	ui, mobile := strings.TrimSpace(*uiDir), strings.TrimSpace(*mobileDir)
+	if ui == "" && mobile == "" {
+		ui, mobile = detectUIRoots()
+	}
+
+	st, err := client.StartDaemon(client.StartOptions{
+		Exe:        selfExe(),
+		MagicAgent: coreExe(),
+		Profile:    *profilePath,
+		UIRoot:     ui,
+		MobileDir:  mobile,
+		Addr:       *addr,
+		Token:      *token,
+		ProxyAddr:  *proxyAddr,
+		BrowseUA:   *browseUA,
+		Lan:        *lan,
+		StatePath:  *statePath,
+		LogPath:    *logPath,
+		Wait:       *wait,
+	})
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client:", err)
+		return 1
+	}
+	printStarted(st)
+	return 0
+}
+
+func runClientStop(args []string) int {
+	fs := newFlagSet("stop")
+	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
+	_ = fs.Parse(args)
+
+	stopped, st, err := client.StopDaemon(client.StopOptions{StatePath: *statePath})
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client:", err)
+		return 1
+	}
+	switch {
+	case stopped:
+		fmt.Printf("已停止（pid %d，端口 %d）\n", st.PID, st.Port)
+	case st == nil:
+		fmt.Println("本来就没在跑")
+	default:
+		fmt.Printf("进程已不在（pid %d），状态文件已清理\n", st.PID)
+	}
+	return 0
+}
+
+func runClientStatus(args []string) int {
+	fs := newFlagSet("status")
+	statePath := fs.String("state", "", "状态文件路径（默认 ~/.magic-client/client.json）")
+	asJSON := fs.Bool("json", false, "输出 JSON（给脚本 / 客户端用）")
+	_ = fs.Parse(args)
+
+	st, err := client.StatusDaemon(*statePath)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "magic-client:", err)
+		return 1
+	}
+	if *asJSON {
+		writeJSONStdout(st)
+		if !st.Running {
+			// 与 systemctl is-active 同一口径：没在跑时退出码非 0，脚本可直接判。
+			return 3
+		}
+		return 0
+	}
+	printStatus(st)
+	if !st.Running {
+		return 3
+	}
+	return 0
+}
+
+// printStarted 启动成功后的说明：**手机能直接用的东西放最前面**。
+func printStarted(st *client.DaemonState) {
+	fmt.Printf("客户端服务已在后台运行（pid %d，端口 %d）\n", st.PID, st.Port)
+	fmt.Printf("  本机     %s\n", st.URL)
+	switch {
+	case len(st.LanAddrs) == 0:
+		fmt.Println("  局域网   （本次只绑了 127.0.0.1，手机连不上；要手机连请加 --lan）")
+	default:
+		for _, u := range st.LanAddrs {
+			fmt.Printf("  手机     %s\n", u)
+		}
+		for _, u := range st.LanAddrs {
+			base := strings.TrimSuffix(u, "/?token="+st.Token)
+			fmt.Printf("  二维码   %s/pair?token=%s  （在电脑上打开，手机扫屏幕）\n", base, st.Token)
+		}
+	}
+	if st.ProxyAddr != "" {
+		fmt.Printf("  SOCKS5   %s（用户名随意，口令 = 令牌）\n", st.ProxyAddr)
+	}
+	fmt.Printf("  日志     %s\n", st.LogPath)
+	fmt.Println("  停止     magic-client stop")
+}
+
+func printStatus(st *client.DaemonStatus) {
+	if st.State == nil {
+		fmt.Println("未运行：" + st.Note)
+		return
+	}
+	s := st.State
+	if !st.Running {
+		fmt.Printf("未运行：%s（端口 %d）\n", st.Note, s.Port)
+		return
+	}
+	fmt.Printf("运行中（pid %d，端口 %d）\n", s.PID, s.Port)
+	fmt.Printf("  本机     %s\n", s.URL)
+	for _, u := range s.LanAddrs {
+		fmt.Printf("  手机     %s\n", u)
+	}
+	if len(s.LanAddrs) == 0 {
+		fmt.Println("  局域网   （未绑局域网，手机连不上）")
+	}
+	if st.Health != nil {
+		fmt.Printf("  应用     %s｜契约 v%d｜引擎 %d 个\n",
+			st.Health.App, st.Health.ContractVersion, st.Health.Engines)
+	}
+	fmt.Printf("  启动于   %s\n", s.StartedAt.Format("2006-01-02 15:04:05"))
+	fmt.Printf("  日志     %s\n", s.LogPath)
+}
+
+// detectUIRoots 按 npm 包布局找界面目录。
+//
+// npm 包把 UI 作为数据文件放在**包根**（node_modules/magic-agent/client-ui），
+// 二进制在 npm/dist/<plat>/ 下 —— 所以从自身往上找包根，看有没有那两个目录。
+// 找不到返回空（只提供接口），这不是错误：纯 API 用法本来就合法。
+func detectUIRoots() (string, string) {
+	dir := filepath.Dir(selfExe())
+	for i := 0; i < 4; i++ {
+		ui := filepath.Join(dir, "client-ui")
+		mobile := filepath.Join(dir, "client-ui-mobile")
+		if isDirPath(ui) {
+			if !isDirPath(mobile) {
+				mobile = ""
+			}
+			return ui, mobile
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			break
+		}
+		dir = parent
+	}
+	return "", ""
+}
+
+// selfExe 当前可执行文件（start 时用它拉起后台 serve）。
+func selfExe() string {
+	p, err := os.Executable()
+	if err != nil {
+		return ""
+	}
+	return p
+}
+
+// coreExe 交给 serve 的 core 路径。
+//
+// 优先级：MAGIC_AGENT_BIN（core 转发时设的，一定是**同一次安装**的那份）> PATH。
+// 为什么不直接让 serve 从 PATH 找：PATH 里可能是另一个版本，契约比对会失败，
+// 而用户看到的是「刚装的这个坏了」。与引擎探测同一条规则（AGENTS.md）。
+func coreExe() string {
+	if p := strings.TrimSpace(os.Getenv("MAGIC_AGENT_BIN")); p != "" {
+		if st, err := os.Stat(p); err == nil && !st.IsDir() {
+			return p
+		}
+	}
+	return ""
+}

package/cmd/magic-client/main.go

@@ -9,6 +9,8 @@
 //
 //	magic-client serve --profile ./profiles/zhantianping.json --ui-dir ./client-ui
 //	magic-client serve --print-url          # 只打印带令牌的地址，不启动（脚本用）
+//	magic-client start --lan                # 后台常驻（关掉终端也还在），手机可连
+//	magic-client status | stop              # 看状态 / 停掉后台实例
 //
 // 默认**只绑 127.0.0.1**，并需要 X-Magic-Token：同机任意进程都能访问本地端口，
 // 不开鉴权等于把引擎执行权交给它们。
@@ -31,19 +33,35 @@ import (
 )
 
 func main() {
-	if len(os.Args) < 2 || os.Args[1] != "serve" {
-		fmt.Fprintln(os.Stderr, "用法: magic-client serve [--profile <path>] [--ui-dir <dir>] [--addr 127.0.0.1:0] [--token <t>]")
+	if len(os.Args) < 2 {
+		fmt.Fprint(os.Stderr, clientUsage)
+		os.Exit(2)
+	}
+	switch os.Args[1] {
+	case "start", "stop", "status":
+		os.Exit(runClientCommandWithExit(os.Args[1], os.Args[2:]))
+	case "serve":
+		// 落下去走下面的前台流程
+	case "-h", "--help", "help":
+		fmt.Print(clientUsage)
+		os.Exit(0)
+	default:
+		fmt.Fprintf(os.Stderr, "magic-client: 未知动作 %q\n\n%s", os.Args[1], clientUsage)
 		os.Exit(2)
 	}
 	fs := flag.NewFlagSet("serve", flag.ExitOnError)
 	var (
 		profilePath = fs.String("profile", "", "profile JSON 路径（空 = 内置默认）")
 		uiDir       = fs.String("ui-dir", "", "静态资源目录（基础版 UI 与业务模块）")
+		mobileDir   = fs.String("mobile-dir", "", "移动端界面目录（client-ui-mobile）。配了之后 /m/ 远程提供它，APK 壳可远程加载、改界面免重打")
 		addr        = fs.String("addr", "", "监听地址（默认 127.0.0.1:0；带 --lan 时是 0.0.0.0:0）")
 		lan         = fs.Bool("lan", false, "绑到局域网（0.0.0.0），让手机 / 平板连得上。⚠️ 开了之后令牌是唯一门锁")
 		token       = fs.String("token", "", "访问令牌（空 = 随机生成并打印；--lan 时至少要 24 个字符）")
 		magicAgent  = fs.String("magic-agent", os.Getenv("MAGIC_AGENT_BIN"), "core 可执行文件（空 = 从 PATH 找 magic-agent）")
 		printURL    = fs.Bool("print-url", false, "只打印带令牌的访问地址后退出（不启动服务）")
+		proxyAddr   = fs.String("proxy-addr", "", "SOCKS5 出口监听地址（供移动端 VPN 隧道核心使用），如 0.0.0.0:1080")
+		browseUA    = fs.String("browse-ua", "", "内置浏览器中转的 User-Agent：mobile（默认）/ desktop / 任意自定义串")
+		readyFile   = fs.String("ready-file", "", "监听成功后把 {pid,port,url,lanAddrs} 原子写到这个路径（`magic-client start` 用它拿端口，别手工传）")
 	)
 	_ = fs.Parse(os.Args[2:])
 
@@ -68,7 +86,9 @@ func main() {
 		MagicAgent: *magicAgent,
 		Profile:    prof,
 		UIRoot:     *uiDir,
+		MobileRoot: *mobileDir,
 		Token:      tok,
+		BrowseUA:   *browseUA,
 	})
 	if err != nil {
 		// 契约不匹配是**要立刻停**的错误：带着不匹配的能力跑起来只会让人以为是界面 bug。
@@ -102,15 +122,19 @@ func main() {
 	fmt.Fprintf(os.Stderr, "magic-client: %s | core=%s 契约 v%d | 引擎 %d 个 | 数据目录 %s\n",
 		prof.App.Name, svc.MagicAgentPath(), c.ContractVersion, len(c.Engines), prof.DataDir())
 	fmt.Fprintf(os.Stderr, "magic-client: 打开 %s\n", url)
+	if strings.TrimSpace(*uiDir) != "" || strings.TrimSpace(*mobileDir) != "" {
+		fmt.Fprintf(os.Stderr, "magic-client: 移动端界面（远程 HTML，改界面免重打 APK）  http://127.0.0.1:%d/m/?token=%s\n", port, tok)
+	}
 	fmt.Fprintf(os.Stderr, "magic-client: 接口 /desk/{health,contract,engines,modules,sessions,profile,asks,ask,ask/{id}/control} + 业务转发 /api/*（都要 X-Magic-Token）\n")
+	var lanAddrs []string
 	if *lan {
 		// 绑到局域网就把可用地址全打出来：一台机器常有多个网卡，猜错比多打两行麻烦。
 		fmt.Fprintln(os.Stderr, "magic-client: ⚠️ 已绑到局域网（0.0.0.0）：同网络内的设备都能访问，令牌是唯一门锁")
-		addrs := client.LanAddresses(port)
-		if len(addrs) == 0 {
+		lanAddrs = client.LanAddresses(port)
+		if len(lanAddrs) == 0 {
 			fmt.Fprintln(os.Stderr, "magic-client: 没找到局域网地址（只连着回环？用 ipconfig getifaddr en0 查一下本机 IP）")
 		}
-		for _, a := range addrs {
+		for _, a := range lanAddrs {
 			fmt.Fprintf(os.Stderr, "magic-client: 手机 / 平板打开  http://%s/?token=%s\n", a, tok)
 			// 配对二维码页：要在**电脑上**打开这个链接（手机扫屏幕上的码）。
 			// 用某个网卡地址打开，码里就是那个地址 —— 所以每个地址各给一条。
@@ -118,6 +142,48 @@ func main() {
 		}
 	}
 
+	// SOCKS5 出口：给移动端 VPN 隧道核心当出口（TUN → SOCKS5）。
+	// 显式开了才起 —— 能连到它的人就能借这台机器上网，令牌是唯一门锁。
+	proxyActual := ""
+	if pa := strings.TrimSpace(*proxyAddr); pa != "" {
+		pln, err := net.Listen("tcp", pa)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "magic-client: SOCKS5 监听失败:", err)
+			os.Exit(1)
+		}
+		go func() {
+			if err := svc.ServeProxy(pln); err != nil {
+				fmt.Fprintln(os.Stderr, "magic-client: SOCKS5 服务退出:", err)
+			}
+		}()
+		proxyActual = pln.Addr().String()
+		fmt.Fprintf(os.Stderr, "magic-client: SOCKS5 出口 %s（用户名随意，口令 = 令牌）\n", proxyActual)
+	} else if *lan {
+		fmt.Fprintln(os.Stderr, "magic-client: 未开 SOCKS5 出口（移动端隧道需要它：加 --proxy-addr 0.0.0.0:1080）")
+	}
+
+	/* ready 文件：`magic-client start` 靠它拿端口（端口是 0 = 系统分配的，
+	   父进程除了读这个文件没有别的可靠途径）。**必须在监听成功之后写** ——
+	   写早了父进程会拿着一个还没 Serve 的端口去探活，白等一轮。 */
+	if p := strings.TrimSpace(*readyFile); p != "" {
+		lanURLs := make([]string, 0, len(lanAddrs))
+		for _, a := range lanAddrs {
+			lanURLs = append(lanURLs, fmt.Sprintf("http://%s/?token=%s", a, tok))
+		}
+		if err := client.WriteReadyFile(p, client.ReadyInfo{
+			Port:      port,
+			Addr:      ln.Addr().String(),
+			URL:       url,
+			Lan:       *lan,
+			LanAddrs:  lanURLs,
+			ProxyAddr: proxyActual,
+		}); err != nil {
+			// 写不出来就直接退出：父进程会一直等不到，报错还不如现在说清楚。
+			fmt.Fprintln(os.Stderr, "magic-client: 写 ready 文件失败:", err)
+			os.Exit(1)
+		}
+	}
+
 	srv := &http.Server{
 		Handler:           svc.Handler(),
 		ReadHeaderTimeout: 10 * time.Second,

package/go.mod

@@ -2,10 +2,13 @@ module github.com/darren/magic-agent
 
 go 1.26.5
 
-require github.com/spf13/cobra v1.10.2
+require (
+	github.com/gorilla/websocket v1.5.3
+	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
+	github.com/spf13/cobra v1.10.2
+)
 
 require (
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e // indirect
-	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
 )

package/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=
@@ -6,7 +8,8 @@ github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e h1:MRM5ITcdelLK2j1
 github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e/go.mod h1:XV66xRDqSt+GTGFMVlhk3ULuV0y9ZmzeVGR4mloJI3M=
 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=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/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=

package/internal/agent/arkclaw.go

@@ -84,9 +84,10 @@ import (
 //
 // 2026-09-24 由 3 分钟提到 10 分钟：3 分钟是按「单轮往返 8~23s」定的，但**带工具循环的
 // 任务会跑很久** —— 实测「生成周报」在网关侧要 304s 才回（期间每 15s 一个 working 心跳），
-// 3 分钟必被砍、正文一个字都拿不到。10 分钟与 CLI 的 -t 默认（600s）对齐，也让流式与非流式
+// 3 分钟必被砍、正文一个字都拿不到。
+// 2026-10-10 再由 10 分钟统一上调到 1 小时，与 CLI 的 -t 默认对齐，也让流式与非流式
 // 两条路的默认一致（非流式走 Runner，拿的就是 -t）。
-const DefaultArkClawTimeout = 10 * time.Minute
+const DefaultArkClawTimeout = time.Hour
 
 // maxArkClawBody 单次响应体读取上限，防止异常响应把内存吃满。
 const maxArkClawBody = 8 << 20 // 8 MiB

package/internal/agent/arkclaw_stream.go

@@ -67,6 +67,19 @@ type arkClawStreamState struct {
 	completed bool   // 是否见过 completed 帧
 	state     string // 最近一次 status.state（错误信息用）
 	sessionID string // contextId（会话锚点，逐帧刷新）
+
+	// tracker 状态收敛的身份与版本（见 itemtracker.go）。
+	textTrack *itemTracker
+	// textTrack 是否已经发过事件（发过就不能再换 item id）。
+	textStarted bool
+}
+
+// trackers 惰性建立跟踪器。
+func (st *arkClawStreamState) trackers() *itemTracker {
+	if st.textTrack == nil {
+		st.textTrack = newItemTracker("arkclaw", laneText)
+	}
+	return st.textTrack
 }
 
 // Stream 实现 Streamer：走 A2A 官方 SSE 通道（见文件头）。
@@ -155,8 +168,24 @@ func (e *ArkClawEngine) Stream(ctx context.Context, req Request, onEvent func(St
 			return StreamResult{Response: resp}, perr
 		}
 		fmt.Fprintln(stderr, "magic-agent: arkclaw 网关未按 SSE 回（message/stream 不可用？），本轮按一次性响应处理（无增量）")
+		// 一次性响应也走 tracker：一次性只是**没有增量帧**，不是**没有状态收敛**。
+		// 收尾发 turn_end（final）而不是又一条 text，与 SSE 路径同一约定。
 		if onEvent != nil && resp.Text != "" {
-			onEvent(StreamEvent{Kind: KindText, Text: resp.Text})
+			fst := &arkClawStreamState{onEvent: onEvent, sessionID: resp.SessionID}
+			// 原生 id 与 SSE 路径同源：一次性 body 里也有 result.id（task id），
+			// 用 arkClawParseResponse 解析出的响应拿不到它，所以这里按帧重解一次。
+			if id := arkClawTaskID(raw); id != "" {
+				fst.trackers().Begin(id)
+			}
+			ev := StreamEvent{Kind: KindText, Text: resp.Text, SessionID: resp.SessionID}
+			// 一次性响应是整段到达，没有前序增量：snapshot 就是全文本身。
+			fst.trackers().nextWith(StatusRunning, resp.Text).apply(&ev)
+			onEvent(ev)
+			end := StreamEvent{Kind: KindTurnEnd, Text: resp.Text, SessionID: resp.SessionID}
+			if attrs, ok := fst.trackers().Finalize(resp.Text); ok {
+				attrs.apply(&end)
+			}
+			onEvent(end)
 		}
 		return StreamResult{Response: resp}, nil
 	}
@@ -171,6 +200,7 @@ func (e *ArkClawEngine) Stream(ctx context.Context, req Request, onEvent func(St
 		}
 		done, herr := st.handleFrame([]byte(payload), req.JSONSchema)
 		if herr != nil {
+			st.fail(herr)
 			return st.result(e, req, start), herr
 		}
 		if done {
@@ -180,18 +210,27 @@ func (e *ArkClawEngine) Stream(ctx context.Context, req Request, onEvent func(St
 	if serr := sc.Err(); serr != nil {
 		// 超时/取消会在读 body 时爆出来（请求头早就到了，卡的是流）。
 		if cerr := httpCtx.Err(); cerr != nil {
-			return st.result(e, req, start), fmt.Errorf("arkclaw: 流式读取中断: %w", cerr)
+			err := fmt.Errorf("arkclaw: 流式读取中断: %w", cerr)
+			st.fail(err)
+			return st.result(e, req, start), err
 		}
-		return st.result(e, req, start), fmt.Errorf("arkclaw: 读取流式响应失败: %w", serr)
+		err := fmt.Errorf("arkclaw: 读取流式响应失败: %w", serr)
+		st.fail(err)
+		return st.result(e, req, start), err
 	}
 
 	if !st.completed {
-		return st.result(e, req, start),
-			fmt.Errorf("arkclaw: 流式响应结束但没有 completed 帧（最后状态 %q）", st.state)
+		err := fmt.Errorf("arkclaw: 流式响应结束但没有 completed 帧（最后状态 %q）", st.state)
+		st.fail(err)
+		return st.result(e, req, start), err
 	}
 	res := st.result(e, req, start)
 	if strings.TrimSpace(res.Text) == "" {
-		return res, fmt.Errorf("arkclaw: 网关返回空正文（流式）")
+		// 正文空 → 整轮没有可用输出。item 可能已建立（网关发过 artifact），
+		// 必须收成 failed，否则那条 item 永远停在 running。
+		err := fmt.Errorf("arkclaw: 网关返回空正文（流式）")
+		st.fail(err)
+		return res, err
 	}
 	return res, nil
 }
@@ -213,6 +252,17 @@ func (st *arkClawStreamState) handleFrame(raw []byte, schema *JSONSchema) (bool,
 	if id := strings.TrimSpace(res.ContextID); id != "" {
 		st.sessionID = id
 	}
+	/* 原生 item id 用 **taskId（res.ID）** 而不是 contextId —— 两者语义不同，
+	   用错会让两轮共用一个 item：
+	   - contextId 是**会话**锚点，跨轮不变（下一轮带着它续接，见
+	     arkClawBuildRequest 的 contextID 参数），拿它当 item id 的话
+	     一个会话里的每一轮都是同一个 item，后一轮覆盖前一轮
+	     （症状：多轮对话只剩最后一次回复）。
+	   - taskId 是**单轮**任务 id，每个 message/stream 一次，天然是一轮一个 item。
+	   两者都拿不到时降级到本轮内稳定的 local_<n>（见 itemTracker.ensure）。 */
+	if id := strings.TrimSpace(res.ID); id != "" && !st.textStarted {
+		st.trackers().Note(id)
+	}
 	state := strings.ToLower(strings.TrimSpace(res.Status.State))
 	st.state = state
 
@@ -237,6 +287,8 @@ func (st *arkClawStreamState) handleFrame(raw []byte, schema *JSONSchema) (bool,
 		st.final = text
 		st.completed = true
 		st.emitText(text)
+		// completed = 轮次终点：发 turn_end 把 item 收成 final（见 finish 的注释）。
+		st.finish()
 		return true, nil
 	}
 
@@ -265,9 +317,61 @@ func (st *arkClawStreamState) emitText(text string) {
 		return
 	}
 	st.emitted.WriteString(text)
-	if st.onEvent != nil {
-		st.onEvent(StreamEvent{Kind: KindText, Text: text})
+	if st.onEvent == nil {
+		return
+	}
+	/* snapshot 直接取 st.emitted（累积到此刻的全文），**不能**喂给 tracker 的
+	   Append —— Append 的语义是「把这段**增量**拼到已有 snapshot 后面」，
+	   而这里传的是「累积到此刻的全文」，两者混用会逐帧翻倍
+	   （「你好」→「你好你好」，与 codebuddy-gateway 踩过的同一个坑）。
+	   正确分工见 itemtracker.go 文件头：tracker 管 id/revision/status，
+	   内容累积由调用方独家负责。 */
+	ev := StreamEvent{Kind: KindText, Text: text}
+	st.trackers().nextWith(StatusRunning, st.emitted.String()).apply(&ev)
+	st.textStarted = true
+	st.onEvent(ev)
+}
+
+// finish 收尾：把 item 标成 final（completed 帧已到，正文不会再变）。
+//
+// 发 **KindTurnEnd** 而不是又一条 KindText，理由同 codebuddy-gateway：
+// completed 是**轮次边界**而非「又一段正文」；补一条空 Text 的 KindText
+// 会打破既有按 ev.Text 收集的消费者（既有测试就是这么写的）。
+// arkclaw 不在 AppendSupportOf 名单里，不会启用常驻会话，
+// 所以不会被误触发 keep-alive 空闲收工。
+func (st *arkClawStreamState) finish() {
+	if st.onEvent == nil || !st.textStarted {
+		return
 	}
+	ev := StreamEvent{Kind: KindTurnEnd, Text: st.final, SessionID: st.sessionID}
+	if attrs, ok := st.trackers().Finalize(st.emitted.String()); ok {
+		attrs.apply(&ev)
+	}
+	st.onEvent(ev)
+}
+
+// fail 收尾异常路径：流被截断 / 任务 failed / JSON-RPC error / 空正文时，把已经发出去的
+// 正文 item 收成 failed，而不是让它永远停在 running（消费方只能靠超时猜，
+// 历史回放更糟：那一条永远显示「生成中」）。
+//
+// 语义与 finish 的分工：turn_end = 网关给了 completed 帧（成功收尾），
+// turn_failed = 没有（异常收尾），带 Error / Reason。partial 的内容仍然存在，
+// 只是这条 item 不会再更新（Status=failed 明确终止增长）。
+func (st *arkClawStreamState) fail(err error) {
+	if st.onEvent == nil || err == nil || !st.textStarted {
+		return
+	}
+	ev := StreamEvent{
+		Kind:      KindTurnFailed,
+		SessionID: st.sessionID,
+		Error:     err.Error(),
+		Reason:    ReasonOf(err),
+		Status:    StatusFailed,
+	}
+	if attrs, ok := st.trackers().Failed(st.emitted.String()); ok {
+		attrs.apply(&ev)
+	}
+	st.onEvent(ev)
 }
 
 // result 把累积状态收成 StreamResult（终态与错误路径共用）。
@@ -306,6 +410,20 @@ func arkClawSSEPayload(line string) (string, bool) {
 	return payload, true
 }
 
+// arkClawTaskID 从一次性响应体里取 task id（result.id）。
+//
+// 非 SSE 回退路径专用：那里走 arkClawParseResponse 拿不到 result 结构
+// （它只返回拼好的 Response），但原生 id 不该因此降级到 local_<n> ——
+// 同一个 task 在 SSE 与一次性两条路径下必须得到**同一个** item id，
+// 否则同一轮回复会因走不同通道而在消费方眼里裂成两条 item。
+func arkClawTaskID(raw []byte) string {
+	env := arkClawEnvelope{}
+	if err := json.Unmarshal(raw, &env); err != nil || env.Result == nil {
+		return ""
+	}
+	return strings.TrimSpace(env.Result.ID)
+}
+
 // arkClawIsEventStream 响应是否为 SSE（content-type 判断，容忍参数与大小写）。
 func arkClawIsEventStream(contentType string) bool {
 	return strings.HasPrefix(strings.ToLower(strings.TrimSpace(contentType)), "text/event-stream")