magic-agent 1.0.3 → 1.0.49

package/internal/cli/attach_test.go

@@ -14,6 +14,8 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/darren/magic-agent/internal/agent"
 )
 
 // writeAttachFile 写一个测试文件（内容随意 —— MIME 由魔数/扩展名嗅探，这里只关心路径链路）。
@@ -156,48 +158,58 @@ func TestAttachmentPromptFallbackWarnUnit(t *testing.T) {
 	if !strings.Contains(gotOff, "--engines") {
 		t.Errorf("提示应指引到 --engines 的 attachments 字段: %q", gotOff)
 	}
-	// dsh / openclaw：同样无原生通道，但 --tools 在它们身上没有落地通道
-	//（自带工具循环）→ 提示里**不该**出现「请改用 --tools on」（传了也不改变行为）。
-	for _, e := range []string{"dsh", "openclaw"} {
-		got := attachmentPromptFallbackWarn(e, 1, true)
-		if !strings.Contains(got, e) || !strings.Contains(got, "没有附件输入通道") {
-			t.Errorf("%s 应提示降级: %q", e, got)
-		}
-		if strings.Contains(got, "--tools on") {
-			t.Errorf("%s 的 --tools 无落地通道，不该提 --tools on: %q", e, got)
-		}
+	// openclaw：无原生通道，且 --tools 在它身上没有落地通道（自带工具循环）→
+	// 提示里**不该**出现「请改用 --tools on」（传了也不改变行为）。
+	gotOpenclaw := attachmentPromptFallbackWarn("openclaw", 1, true)
+	if !strings.Contains(gotOpenclaw, "openclaw") || !strings.Contains(gotOpenclaw, "没有附件输入通道") {
+		t.Errorf("openclaw 应提示降级: %q", gotOpenclaw)
+	}
+	if strings.Contains(gotOpenclaw, "--tools on") {
+		t.Errorf("openclaw 的 --tools 无落地通道，不该提 --tools on: %q", gotOpenclaw)
+	}
+	// dsh：SDK 通道（默认）原生收图 → 有原生通道，不该有任何降级提示。
+	t.Setenv(agent.DshProfileEnv, "")
+	if got := attachmentPromptFallbackWarn("dsh", 1, true); got != "" {
+		t.Errorf("dsh(SDK 通道) 有原生通道，不该提示降级: %q", got)
 	}
 }
 
-// 端到端：trae（无原生通道）带附件 + 默认 --tools off → stderr 出现降级提示。
+// 端到端：trae（无原生通道）带附件 → stderr 出现降级提示，但不再提 --tools off
+// （2026-10-01 默认从 off 反转为 on —— trae 默认工具已开，附件还是降级，但**不要**
+// 再提示「请改用 --tools on」，因为已经是 on 了；提示要瘦身、避免噪音）。
 func TestAttachFlagWarnsOnPromptFallbackEngine(t *testing.T) {
 	registerFake(&stringEngine{name: "trae", text: "ok"})
 	img := writeAttachFile(t, "shot.png", "\x89PNG\r\n\x1a\n")
 
+	// 默认 --tools on：仍提示降级（trae 自身问题，与工具开关无关），但**不**提 --tools off
 	_, stderr, err := runAskCmd(t, "", "-e", "trae", "-p", "看图", "-a", img)
 	if err != nil {
 		t.Fatalf("ask: %v", err)
 	}
-	if !strings.Contains(stderr, "没有附件输入通道") || !strings.Contains(stderr, "--tools off") {
-		t.Errorf("stderr 应给出降级提示, got %q", stderr)
+	if !strings.Contains(stderr, "没有附件输入通道") {
+		t.Errorf("默认状态仍应提示降级, got %q", stderr)
+	}
+	if strings.Contains(stderr, "--tools off") {
+		t.Errorf("默认 --tools on，不该再提 --tools off: %q", stderr)
 	}
 
-	// --tools on → 只提示降级，不再提读不到
-	_, stderrOn, err := runAskCmd(t, "", "-e", "trae", "-p", "看图", "--tools", "on", "-a", img)
+	// --tools off → 必须点明读不到（反向场景仍然要明确警告）
+	_, stderrOff, err := runAskCmd(t, "", "-e", "trae", "-p", "看图", "--tools", "off", "-a", img)
 	if err != nil {
 		t.Fatalf("ask: %v", err)
 	}
-	if !strings.Contains(stderrOn, "没有附件输入通道") {
-		t.Errorf("仍应提示降级, got %q", stderrOn)
+	if !strings.Contains(stderrOff, "没有附件输入通道") {
+		t.Errorf("仍应提示降级, got %q", stderrOff)
 	}
-	if strings.Contains(stderrOn, "--tools off") {
-		t.Errorf("工具已开，不该再提 --tools off: %q", stderrOn)
+	if !strings.Contains(stderrOff, "--tools off") || !strings.Contains(stderrOff, "--tools on") {
+		t.Errorf("显式 --tools off 时必须点明读不到 + 指引 --tools on: %q", stderrOff)
 	}
 }
 
 // ── --engines 的 attachments 字段 ────────────────────────────
 
 func TestEnginesFlagCarriesAttachmentsCapability(t *testing.T) {
+	t.Setenv(agent.DshProfileEnv, "") // dsh 默认 SDK 通道 → 原生收图
 	registerFake(&stringEngine{name: "codex"})
 	registerFake(&stringEngine{name: "claude"})
 	registerFake(&stringEngine{name: "arkclaw"})
@@ -224,7 +236,7 @@ func TestEnginesFlagCarriesAttachmentsCapability(t *testing.T) {
 		"claude":  "stdin:stream-json",
 		"arkclaw": "part:file",
 		"trae":    "prompt",
-		"dsh":     "prompt", // headless 无附件参数 → 路径写进提示词
+		"dsh":     "sdk:content-blocks", // SDK 通道原生 image 块 → 真进模型上下文
 	} {
 		if got[engine] != want {
 			t.Errorf("--engines 里 %s 的 attachments = %q want %q", engine, got[engine], want)

package/internal/cli/clientcmd.go

@@ -0,0 +1,156 @@
+package cli
+
+// clientcmd.go - `magic-agent client <args...>`：把客户端插件的后台管理动作转给 magic-client。
+//
+// ── 为什么是「转发」而不是「在这里实现」 ──
+// `internal/boundary` 钉着一条硬约束：core 的依赖闭包里不许出现 `internal/client`
+//（桌面 / 移动端是**可选**插件，不装插件时 core 必须照旧能跑）。所以 core 不能调用
+// StartDaemon 这类函数 —— 它只做一件 core 该做的事：找到那个可执行文件，把参数原样交出去。
+//
+// ── 为什么不解析参数 ──
+// 参数集合由 magic-client 自己定义（--lan / --ui-dir / --port…）。在 core 里再抄一份，
+// 两份迟早分叉，而分叉的表现是「core 认的 flag 插件不认」这种最难查的错。
+// 所以这里 DisableFlagParsing，`client` 之后的一切原样透传，**包括 --help**。
+//
+// ── 为什么设置 MAGIC_AGENT_BIN ──
+// magic-client 启动服务时要调 core 的 `--contract`。让它拿 PATH 里那份，
+// 会和「你正在用的这份 core」不一致（版本不同 → 契约校验直接失败）。
+// 把自己交出去，版本必然对得上。
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// clientSubcommand 构造 `client` 子命令。
+func clientSubcommand() *cobra.Command {
+	return &cobra.Command{
+		Use:   "client <start|stop|status> [flags]",
+		Short: "客户端插件（magic-client）：后台启动 / 停止 / 看状态，手机据此连接",
+		Long: `把参数原样交给 magic-client（客户端插件，随 npm 包一起安装）。
+
+  magic-agent client start --lan     # 后台常驻，打印手机可用的地址与配对二维码
+  magic-agent client status          # 在不在、端口、手机地址、健康检查
+  magic-agent client stop            # 停掉（本来没跑也算成功）
+
+为什么要有 start 而不是直接 serve：serve 是前台进程，关掉终端就没了；端口又由系统分配，
+下次启动换一个 —— 用户既记不住也没法配对。start 会把 pid / 端口 / 令牌落成一份 0600 的
+状态文件（~/.magic-client/client.json），三个动作围绕它工作，令牌跨重启稳定
+（存 ~/.magic-client/token，删掉它才会换）。
+
+⚠️ --lan 只绑局域网：手机要和这台电脑在**同一个 Wi-Fi**。跨网访问不在本命令范围内。
+
+本命令不在 core 里实现，只负责转发（桌面 / 移动端是可选插件，core 不依赖它）。
+详细 flag 见 magic-client start --help。`,
+		// 参数原样透传：包括 --lan / --help。cobra 自己别再解析。
+		DisableFlagParsing: true,
+		// 兼容 `magic-agent client`（无子动作）—— 交给 magic-client，它会打印自己的用法。
+		Args: cobra.ArbitraryArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			exe, err := resolveClientExe()
+			if err != nil {
+				return err
+			}
+			return execClient(cmd, exe, args)
+		},
+	}
+}
+
+// resolveClientExe 定位 magic-client 可执行文件。
+//
+// 顺序：MAGIC_CLIENT_BIN > 与 core 同目录 > PATH > npm 全局前缀。
+// 同目录排第二是因为 npm 包里两个二进制并排放（npm/dist/<plat>/），
+// 而 PATH 里那份可能是别处装的、版本不一致的旧货。
+func resolveClientExe() (string, error) {
+	name := "magic-client"
+	if runtime.GOOS == "windows" {
+		name = "magic-client.exe"
+	}
+	if p := strings.TrimSpace(os.Getenv("MAGIC_CLIENT_BIN")); p != "" {
+		if _, err := os.Stat(p); err == nil {
+			return p, nil
+		}
+		return "", fmt.Errorf("MAGIC_CLIENT_BIN 指向的文件不存在：%s", p)
+	}
+	if self, err := os.Executable(); err == nil {
+		// npm 的 bin 转发层拉起的是 npm/dist/<plat>/magic-agent，邻居正是 magic-client。
+		if cand := filepath.Join(filepath.Dir(self), name); isRegularFile(cand) {
+			return cand, nil
+		}
+	}
+	if p, err := exec.LookPath(name); err == nil {
+		return p, nil
+	}
+	// npm 全局前缀兜底：PATH 没带上时（nvm / 自定义 prefix）也能找到。
+	if p := npmPrefixClientExe(name); p != "" {
+		return p, nil
+	}
+	return "", fmt.Errorf("找不到 %s：重装 npm 包（npm i -g magic-agent）应自带它，或用 MAGIC_CLIENT_BIN 指定路径", name)
+}
+
+// npmPrefixClientExe 在 npm 全局前缀下找 magic-client。
+//
+// 与引擎探测的最后一条同源（见 internal/agent/engine_base.go）：读 NPM_CONFIG_PREFIX
+// 而不是 `npm config get prefix` —— 后者会跑一个进程且结果随 PATH 变，慢且不稳。
+func npmPrefixClientExe(name string) string {
+	prefix := strings.TrimSpace(os.Getenv("NPM_CONFIG_PREFIX"))
+	if prefix == "" {
+		return ""
+	}
+	cand := filepath.Join(prefix, "bin", name)
+	if runtime.GOOS == "windows" {
+		cand = filepath.Join(prefix, name)
+	}
+	if isRegularFile(cand) {
+		return cand
+	}
+	return ""
+}
+
+func isRegularFile(p string) bool {
+	st, err := os.Stat(p)
+	return err == nil && !st.IsDir()
+}
+
+// execClient 原样转发 stdio 与退出码。
+func execClient(cmd *cobra.Command, exe string, args []string) error {
+	c := exec.Command(exe, args...)
+	c.Stdin, c.Stdout, c.Stderr = os.Stdin, cmd.OutOrStdout(), cmd.ErrOrStderr()
+	if wd, err := os.Getwd(); err == nil {
+		c.Dir = wd // 沿用调用方的 cwd：core 不传 -w 时默认工作空间就是它
+	}
+	env := os.Environ()
+	if self, err := os.Executable(); err == nil {
+		// 让插件用**这一份** core 校验契约，而不是 PATH 里那份。
+		env = append(env, "MAGIC_AGENT_BIN="+self)
+	}
+	c.Env = env
+
+	if err := c.Run(); err != nil {
+		var ee *exec.ExitError
+		if errors.As(err, &ee) {
+			// 退出码是契约的一部分（2 = 参数错），原样带出去，别一律 1。
+			// 子进程已经把话说完了（它自己的 stderr），这里不要再叠一句。
+			return &exitCodeError{code: ee.ExitCode()}
+		}
+		return fmt.Errorf("启动 %s 失败：%w", filepath.Base(exe), err)
+	}
+	return nil
+}
+
+// exitCodeError 子进程已给出退出码与输出，只差把它带出去。
+//
+// Is(errReportedSentinel) 让 Execute 跳过「再打一遍错误」：转发层的错误文案
+// 只会盖住插件自己的说明（那才是用户要看的那句）。
+type exitCodeError struct{ code int }
+
+func (e *exitCodeError) Error() string { return fmt.Sprintf("子进程退出码 %d", e.code) }
+
+func (e *exitCodeError) Is(target error) bool { return target == errReportedSentinel }

package/internal/cli/events.go

@@ -35,6 +35,7 @@ type eventSink struct {
 	mu      sync.Mutex
 	seq     int
 	session string
+	run     string
 }
 
 func newEventSink(w io.Writer, engine string, enabled bool) *eventSink {
@@ -69,6 +70,25 @@ func (s *eventSink) sessionID() string {
 	return s.session
 }
 
+// setRunID 记住本次运行 id（core 自己生成，引擎可能整轮都不给 session_id）。
+// 只在 ready 行带出去：客户端要靠它把「正在跑但还没有 session_id」的轮次
+// 对应回登记表里以 run_id 为键的那条会话（见 /desk/asks 的 run 字段）。
+func (s *eventSink) setRunID(id string) {
+	if id == "" {
+		return
+	}
+	s.mu.Lock()
+	s.run = id
+	s.mu.Unlock()
+}
+
+// runID 当前运行的 run_id。
+func (s *eventSink) runID() string {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.run
+}
+
 func (s *eventSink) writeLine(b []byte) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -143,6 +163,9 @@ func (s *eventSink) ready(model string) error {
 	if model != "" {
 		attrs["model"] = model
 	}
+	if run := s.runID(); run != "" {
+		attrs["run_id"] = run
+	}
 	return s.eventAttrs(attrs)
 }
 
@@ -161,7 +184,11 @@ func (s *eventSink) notice(kind string, attrs map[string]any) error {
 }
 
 // streamEventPayload 流式事件的 wire 形状 —— `--stream` 与 `--stream --events` 共用。
-// 两边的字段集必须只差 v / seq，test 里有专门的防漂断言。
+// 两条边的字段集必须只差 v / seq，test 里有专门的防漂断言。
+//
+// ⚠️ 状态收敛字段（item_id / item_revision / status / snapshot / error / reason）
+// 只在**非空时**出现（全部 omitempty）—— 老引擎（trae 走 delta 但无 item 概念）、
+// 老事件（turn_end 之外的轮次事件）不带这些字段时与历史逐字节一致。
 func streamEventPayload(ev agent.StreamEvent) any {
 	return struct {
 		Type      string            `json:"type"`
@@ -171,14 +198,32 @@ func streamEventPayload(ev agent.StreamEvent) any {
 		ToolKind  string            `json:"tool_kind,omitempty"`
 		SessionID string            `json:"session_id,omitempty"`
 		Ask       *agent.AskRequest `json:"ask,omitempty"`
+		/* 状态收敛四元组（2026-10-02，对齐 agents-anywhere 的 timeline item）。
+		   消费方按 (item_id, item_revision) 覆盖式 upsert 即可：
+		   同一 item 的多个 partial 帧 + 最后一个 final 帧，
+		   乱序到达也能收敛到正确结果（重复投递同 revision 天然幂等）。 */
+		ItemID       string `json:"item_id,omitempty"`
+		ItemRevision uint64 `json:"item_revision,omitempty"`
+		Status       string `json:"status,omitempty"`
+		Snapshot     string `json:"snapshot,omitempty"`
+		/* 异常收尾（仅 turn_failed）：Error 是完整错误链，Reason 是最内层根因，
+		   与 -o json 的失败 envelope 同源（都走 agent.ReasonOf）。 */
+		Error  string `json:"error,omitempty"`
+		Reason string `json:"reason,omitempty"`
 	}{
-		Type:      string(ev.Kind),
-		Text:      ev.Text,
-		Name:      ev.Name,
-		ID:        ev.ID,
-		ToolKind:  toolKindOfEvent(ev),
-		SessionID: ev.SessionID,
-		Ask:       ev.Ask,
+		Type:         string(ev.Kind),
+		Text:         ev.Text,
+		Name:         ev.Name,
+		ID:           ev.ID,
+		ToolKind:     toolKindOfEvent(ev),
+		SessionID:    ev.SessionID,
+		Ask:          ev.Ask,
+		ItemID:       ev.ItemID,
+		ItemRevision: ev.ItemRevision,
+		Status:       string(ev.Status),
+		Snapshot:     ev.Snapshot,
+		Error:        ev.Error,
+		Reason:       ev.Reason,
 	}
 }
 

package/internal/cli/events_test.go

@@ -19,6 +19,18 @@ func sinkSamples() []agent.StreamEvent {
 		{Kind: agent.KindToolResult, Text: "输出", ID: "toolu_1"},
 		{Kind: agent.KindTurnEnd, Text: "本轮正文", SessionID: "sess_abc"},
 		{Kind: agent.KindAsk, Text: "要选一个"},
+		// 状态收敛样本（2026-10-02）：这两个字段为空时全部 omitempty，
+		// 所以老形状逐字节不变；非空时按契约出现在 wire 上。
+		{
+			Kind: agent.KindText, Text: "片", ItemID: "claude_msg_1",
+			ItemRevision: 3, Status: agent.StatusRunning, Snapshot: "整段",
+		},
+		{
+			Kind: agent.KindTurnFailed, Text: "", SessionID: "sess_abc",
+			Error:  "claude CLI stream ended without result line",
+			Reason: "without result line",
+			Status: agent.StatusFailed, ItemID: "claude_msg_1", ItemRevision: 4,
+		},
 	}
 }
 
@@ -164,3 +176,221 @@ func TestControlConflictsWithStdinPrompt(t *testing.T) {
 		t.Errorf("报错应解释 stdin 冲突，实际: %v", err)
 	}
 }
+
+// TestStreamEventPayloadConvergenceFields 状态收敛字段必须**只增不改**：
+// 老消费者按老形状解析时，这些字段要么不出现（omitempty），要么是它
+// 完全不认识但无害的扩展字段。契约的「只增字段不升版本」规则靠这条钉住。
+func TestStreamEventPayloadConvergenceFields(t *testing.T) {
+	// 1) 空的收敛字段 → 老形状逐字节不变（不带任何新键）。
+	var buf bytes.Buffer
+	if err := newEventSink(&buf, "claude", false).stream(agent.StreamEvent{
+		Kind: agent.KindText, Text: "正文",
+	}); err != nil {
+		t.Fatal(err)
+	}
+	m := decodeEventLine(t, buf.String())
+	for _, k := range []string{"item_id", "item_revision", "status", "snapshot", "error", "reason"} {
+		if _, ok := m[k]; ok {
+			t.Errorf("空收敛字段不该出现在 wire 上：%q -> %v", k, m)
+		}
+	}
+
+	// 2) 非空 → 按契约名出现，值逐项透传。
+	buf.Reset()
+	ev := agent.StreamEvent{
+		Kind: agent.KindText, Text: "片", ItemID: "claude_msg_1",
+		ItemRevision: 3, Status: agent.StatusRunning, Snapshot: "整段",
+	}
+	if err := newEventSink(&buf, "claude", true).stream(ev); err != nil {
+		t.Fatal(err)
+	}
+	m = decodeEventLine(t, buf.String())
+	if m["item_id"] != "claude_msg_1" {
+		t.Errorf("item_id = %v", m["item_id"])
+	}
+	if int(m["item_revision"].(float64)) != 3 {
+		t.Errorf("item_revision = %v", m["item_revision"])
+	}
+	if m["status"] != "running" {
+		t.Errorf("status = %v", m["status"])
+	}
+	if m["snapshot"] != "整段" {
+		t.Errorf("snapshot = %v", m["snapshot"])
+	}
+	// text 仍是增量（不因收敛字段改成整段）。
+	if m["text"] != "片" {
+		t.Errorf("text 应保持增量语义，实际 %v", m["text"])
+	}
+}
+
+// TestTurnFailedPayloadFields turn_failed 必须带 error / reason ——
+// 消费方（jq 管道 / 桌面壳）靠它才知道这一轮为什么没结果。
+func TestTurnFailedPayloadFields(t *testing.T) {
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "claude", true)
+	if err := s.stream(agent.StreamEvent{
+		Kind: agent.KindTurnFailed, SessionID: "s1",
+		Error:  "claude CLI stream ended without result line",
+		Reason: "without result line", Status: agent.StatusFailed,
+	}); err != nil {
+		t.Fatal(err)
+	}
+	m := decodeEventLine(t, buf.String())
+	if m["type"] != "turn_failed" {
+		t.Errorf("type = %v", m["type"])
+	}
+	if m["error"] == "" || m["reason"] == "" {
+		t.Errorf("turn_failed 必须带 error 与 reason：%v", m)
+	}
+	if m["status"] != "failed" {
+		t.Errorf("status = %v，want failed", m["status"])
+	}
+	if m["session_id"] != "s1" {
+		t.Errorf("session_id = %v", m["session_id"])
+	}
+}
+
+// ── 黄金样本：钉住 Claude / CodeBuddy 在 wire 上的真实字节形状 ──
+//
+// 为什么不复用上面的 TestStreamEventPayloadConvergenceFields：
+// 那条验的是「字段在不在、值对不对」；这条验的是**引擎实际跑出来的形状**
+// 与 2026-10-02 真实抓包逐字节一致。两者不能互相替代：
+//   · 字段级断言在「字段改名」时会跟着改，永远发现不了改名带来的破坏；
+//   · 本文件一旦要改（比如某天决定 snapshot 不再随 text 下发），
+//     这里的差异会直接把改动暴露出来，逼人确认影响面。
+//
+// 样本来自真实运行（claude / codebuddy 各自一轮，见 2026-10-01 日志）。
+// 形状的**关键不变量**（改动时最容易被忽略的三条）：
+//  1. `text` 是增量，不是 snapshot —— 终端直打靠它逐行拼。
+//  2. `snapshot` 与 `item_revision` 同时出现且 revision 从 1 起单调。
+//  3. thinking 与 text 的 item_id **不同但后缀相同**（同一原生 message id）。
+//     曾经写成同一个 id，导致覆盖式 upsert 静默吞掉思考内容。
+
+// TestClaudeWireShapeGolden 真实 Claude 一轮的完整事件序列（黄金样本）。
+func TestClaudeWireShapeGolden(t *testing.T) {
+	// 实测：message_start 给出原生 id msg_070d0c14…，思考与正文各自成 lane。
+	live := []agent.StreamEvent{
+		{
+			Kind: agent.KindThinking, Text: "先",
+			ItemID: "claude_think_msg_070d0c14", ItemRevision: 1,
+			Status: agent.StatusRunning, Snapshot: "先",
+		},
+		{
+			Kind: agent.KindThinking, Text: "想一下",
+			ItemID: "claude_think_msg_070d0c14", ItemRevision: 2,
+			Status: agent.StatusRunning, Snapshot: "先想一下",
+		},
+		{
+			Kind: agent.KindText, Text: "2",
+			ItemID: "claude_msg_msg_070d0c14", ItemRevision: 1,
+			Status: agent.StatusRunning, Snapshot: "2",
+		},
+		{
+			Kind: agent.KindTurnEnd, Text: "2", SessionID: "sess_1",
+			ItemID: "claude_msg_msg_070d0c14", ItemRevision: 2,
+			Status: agent.StatusFinal, Snapshot: "2",
+		},
+	}
+
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "claude", false)
+	for _, ev := range live {
+		if err := s.stream(ev); err != nil {
+			t.Fatal(err)
+		}
+	}
+	lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if len(lines) != len(live) {
+		t.Fatalf("行数 = %d，want %d", len(lines), len(live))
+	}
+
+	// 不变量 1：text 恒为增量。
+	for i, ev := range live {
+		m := decodeEventLine(t, lines[i])
+		if m["text"] != ev.Text {
+			t.Errorf("[%d] text = %v，want %v（text 必须是增量，不能被 snapshot 顶掉）", i, m["text"], ev.Text)
+		}
+	}
+
+	// 不变量 2：同一 item 内 revision 从 1 起单调。
+	lastByItem := map[string]float64{}
+	for i, ln := range lines {
+		m := decodeEventLine(t, ln)
+		id, _ := m["item_id"].(string)
+		rev, _ := m["item_revision"].(float64)
+		if id == "" || rev == 0 {
+			t.Errorf("[%d] 缺 item_id / item_revision: %v", i, m)
+			continue
+		}
+		if prev := lastByItem[id]; rev <= prev {
+			t.Errorf("[%d] item %q 的 revision 未单调：%v 之后是 %v", i, id, prev, rev)
+		}
+		lastByItem[id] = rev
+	}
+
+	// 不变量 3：思考与正文两条 item，后缀相同（同一原生 message id）。
+	thinkItem := decodeEventLine(t, lines[0])["item_id"].(string)
+	textItem := decodeEventLine(t, lines[2])["item_id"].(string)
+	if thinkItem == textItem {
+		t.Fatalf("思考与正文共用 item id（会静默吞掉思考内容）: %q", thinkItem)
+	}
+	if !strings.HasSuffix(thinkItem, "msg_070d0c14") || !strings.HasSuffix(textItem, "msg_070d0c14") {
+		t.Errorf("两条 item 应内嵌同一原生 id：%q / %q", thinkItem, textItem)
+	}
+	if !strings.Contains(thinkItem, "think_") {
+		t.Errorf("思考 item id 应含 think_ 段：%q", thinkItem)
+	}
+
+	// 终帧：final 挂在正文 item 上，且是它的最高 revision。
+	end := decodeEventLine(t, lines[3])
+	if end["status"] != string(agent.StatusFinal) {
+		t.Errorf("turn_end.status = %v，want final", end["status"])
+	}
+	if end["item_id"] != textItem {
+		t.Errorf("turn_end 应挂在正文 item 上：%v vs %v", end["item_id"], textItem)
+	}
+}
+
+// TestCodeBuddyWireShapeGolden 真实 CodeBuddy 一轮的形状（黄金样本）。
+//
+// 与 Claude 的**关键差异**：codebuddy 是 AggregateOnly（正文只在 assistant
+// 聚合行出现），所以一轮里通常**没有 thinking lane** —— 只有正文一条 item，
+// 且 text 已是整段（不是逐字增量）。
+func TestCodeBuddyWireShapeGolden(t *testing.T) {
+	live := []agent.StreamEvent{
+		{
+			Kind: agent.KindText, Text: "2",
+			ItemID: "codebuddy_msg_01a0f598", ItemRevision: 1,
+			Status: agent.StatusRunning, Snapshot: "2",
+		},
+		{
+			Kind: agent.KindTurnEnd, Text: "2", SessionID: "sess_cb",
+			ItemID: "codebuddy_msg_01a0f598", ItemRevision: 2,
+			Status: agent.StatusFinal, Snapshot: "2",
+		},
+	}
+	var buf bytes.Buffer
+	s := newEventSink(&buf, "codebuddy", false)
+	for _, ev := range live {
+		if err := s.stream(ev); err != nil {
+			t.Fatal(err)
+		}
+	}
+	lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if len(lines) != 2 {
+		t.Fatalf("行数 = %d，want 2", len(lines))
+	}
+	// 不带 thinking lane：整轮只有一条 item。
+	first := decodeEventLine(t, lines[0])
+	second := decodeEventLine(t, lines[1])
+	if first["item_id"] != second["item_id"] {
+		t.Errorf("codebuddy 整轮应共用一条 item：%v vs %v", first["item_id"], second["item_id"])
+	}
+	if first["status"] != string(agent.StatusRunning) || second["status"] != string(agent.StatusFinal) {
+		t.Errorf("状态序列 = %v → %v，want running → final", first["status"], second["status"])
+	}
+	// 前缀正确（不同引擎的 id 空间不互通，撞了会让跨引擎回放串台）。
+	if !strings.HasPrefix(first["item_id"].(string), "codebuddy_msg_") {
+		t.Errorf("codebuddy item id 前缀不对：%v", first["item_id"])
+	}
+}