magic-agent 1.0.3 → 1.0.49

package/internal/agent/engine_base.go

@@ -27,6 +27,7 @@ import (
 //	│ Continue     │ --continue               │ --continue                │ --resume（自动选最近会话） │ -c               │ resume --last         │ sessions 查最新 id  │ 不支持（显式报错）⑨  │
 //	│ MaxTokens    │ --settings（env 注入）①  │ --settings（env 注入）①   │ 不支持（静默忽略）②        │ -o max_tokens    │ 不支持（静默忽略）②   │ 静默忽略②           │ 静默忽略②            │
 //	│ Temperature  │ 不支持                   │ 不支持                    │ 不支持（静默忽略）②        │ -o temperature   │ 不支持（静默忽略）②   │ 静默忽略②           │ 静默忽略②            │
+//	│ Reasoning    │ --effort <l>             │ --effort <l>              │ 不支持（忽略）             │ 不支持           │ -c reasoning_effort   │ 不支持              │ 不支持               │
 //	│ Tools        │ --tools / 档位③         │ --tools / 档位③          │ --disallowed-tool / 全放行③│ 不支持           │ -s 沙箱档位④          │ 内嵌 agent（忽略）  │ 内嵌 agent（忽略）⑨  │
 //	│ Permission   │ --permission-mode⑧      │ --permission-mode⑧        │ 未接线（yaml 配置）        │ 不支持           │ 未接线（沙箱×审批两轴）│ 未接线（exec.mode） │ 未接线（配置层预设）⑨│
 //	│ SystemPrompt │ --append-system-prompt   │ --append-system-prompt    │ 展平进 prompt 头部         │ -s               │ -c developer_instr.⑤  │ 展平进 prompt 头部  │ 展平进 prompt 头部   │
@@ -100,13 +101,22 @@ import (
 // SessionID / Continue：headless 一次调用 = 一个**全新的持久化 Agent**，官方 app 参数表里只有任务文本、没有续接参数 → **显式报错**（静默开新会话会让调用方以为上下文接上了）。
 // MaxTokens / Temperature：无对应 flag（超时是 provider 级 settings 的 streamIdleTimeoutMs，不是 CLI flag）→ 静默忽略②。
 // Tools：dsh 自带 agent 工具循环（base bundle 的 read/write/edit + Bash），增删工具只能改 profile bundle / cordis.patch.yml，**无命令行级逐工具开关** → 整体忽略（与 openclaw 的「内嵌 agent」同构）。
-// Permission：新会话默认 workspace-write 预设（写入限工作区 + 平台临时目录），另有 read-only 预设，进程回退由环境变量 DSH_PERMISSION_MODE 决定；两个预设无法表达四档模型里的「沙箱关闭 / 无审批」（第 4 档）→ 不接线（none），显式传 --permission 在 CLI 层 exit 2。
+// Permission：**已接线** —— 档位走子进程环境变量 DSH_PERMISSION_MODE（dsh 无逐调用权限 flag）。四档映射 read-only / workspace-write / danger-full-access，第 4 档 = danger-full-access（沙箱关闭 + 审批 never）。核实来源与两处已知差异见 permission.go::dshPermissionMode。
 // SystemPrompt：无独立 system 注入 flag → 展平进 prompt 头部（同 trae/openclaw）。
 // Workspace：官方语义就是「调用时所在目录即默认 workspace 根」→ 子进程 cwd⑥。
 // JSONSchema：无原生约束 → 输出后处理抽 JSON（同 llm/openclaw/arkclaw）。
 // Attachments：无原生输入通道 → 绝对路径写进提示词（同 trae/openclaw）。
 // Stream：实现了，但**只流推理** —— 推理增量走 stderr（"dsh: reasoning:" 起头）→ 逐条 thinking 事件；正文在 turn 结束时一次性给出（一条 text 事件）。正文级流式需 --profile sdk 的 JSON-RPC，不在本引擎范围。
 //
+// ⑩ Reasoning（推理/思考档位，--reasoning，默认 max；取值 minimal/low/medium/high/xhigh/max，off = 不传）：
+//
+//	claude    `--effort <level>`（只认 low/medium/high/xhigh/max，minimal 降级为 low，已实测 --help）
+//	codebuddy `--effort <level>`（同上五档 + minimal；codebuddy-ai 同族同映射）
+//	codex     `-c model_reasoning_effort="<level>"`（exec 与 exec resume 均生效）
+//	trae / llm / openclaw / dsh / arkclaw 无对应参数 → 静默忽略（用户显式传时 CLI 层打一行提示）；
+//	llm 直连的思考由 ~/.magic-agent/models.json 的 extraBody 决定，本字段不注入请求体。
+//	机器可读判断见 ReasoningSupportOf。
+//
 // cliBase 描述一个 CLI 引擎的可执行文件探测配置。
 // 各引擎保留顶层 BinPath 字段与一行式 Name()，以保证测试中零值/复合字面量构造的兼容性；
 // 本结构体仅承载探测链配置，由各引擎的 bin()/Detect() 委托调用。
@@ -169,7 +179,13 @@ var (
 		binName: "llm",
 		envVar:  "MAGIC_AGENT_LLM_BIN",
 		candidates: []string{
-			// venv 优先：绕开 Homebrew Python 3.14 的 pip truststore 兼容问题
+			// venv 优先：绕开 Homebrew Python 3.14 的 pip truststore 兼容问题。
+			// ⚠️ **两个平台的 venv 布局不同，两条都要列**（2026-10-01 实测踩过）：
+			// Windows 的 venv 可执行文件在 `Scripts\`，Unix 在 `bin/`。只列 Unix 那条时，
+			// `npm i -g magic-agent` 的 postinstall 明明把 llm 装好了（install.js 自己
+			// 按 win32 选了 Scripts），`--engines` 却仍报 "llm CLI not found" ——
+			// 安装器与探测器对「llm 装在哪」各说各话，且两边都不报错，很难查。
+			"~/.llm-venv/Scripts/llm.exe",
 			"~/.llm-venv/bin/llm",
 			"/opt/homebrew/bin/llm",
 			"/usr/local/bin/llm",
@@ -391,6 +407,34 @@ func InstallCommandOf(engine string) string {
 	return ""
 }
 
+// ReasoningLevel 归一化推理档位：空串与 off/none/disabled 都返回 ""（= 不追加参数，
+// 让 CLI 用自身默认）；其余原样小写返回。
+func ReasoningLevel(level string) string {
+	switch level = strings.ToLower(strings.TrimSpace(level)); level {
+	case "", "off", "none", "disabled":
+		return ""
+	}
+	return level
+}
+
+// ValidReasoningLevel 校验 --reasoning 的取值（"max" 为 CLI 默认档）。
+func ValidReasoningLevel(level string) bool {
+	switch ReasoningLevel(level) {
+	case "", "minimal", "low", "medium", "high", "xhigh", "max":
+		return true
+	}
+	return false
+}
+
+// ReasoningSupportOf 报告引擎是否有原生推理档位参数（无参引擎传了也会被忽略）。
+func ReasoningSupportOf(engine string) bool {
+	switch engine {
+	case "claude", "codebuddy", "codebuddy-ai", "codex":
+		return true
+	}
+	return false
+}
+
 /* EngineVersionOf 尽力读出某引擎 CLI 的**当前版本**（读不到就空串 —— 绝不编）。
  *
  * 为什么要它（2026-09-23 用户：「引擎检测除了 a2a 的 其他也要支持有升级」）：

package/internal/agent/engine_base_test.go

@@ -248,6 +248,35 @@ func TestCLIResolveEnvVar(t *testing.T) {
 	}
 }
 
+// TestLLMBaseCoversBothVenvLayouts llm 的 venv 探测候选必须同时覆盖
+// **两个平台的 venv 布局**：Windows 是 `Scripts\`，Unix 是 `bin/`。
+//
+// 这条挡的是 2026-10-01 实测踩到的一个真实故障：`npm i -g magic-agent` 的
+// postinstall 明明把 llm 装进了 `~/.llm-venv/Scripts/`（install.js 自己按
+// win32 选 Scripts），`--engines` 却仍报 "llm CLI not found" —— 因为
+// llmBase.candidates 只列了 Unix 的 `bin/` 一条。安装器与探测器各说各话，
+// 两边都不报错，排查成本很高。
+//
+// 断言只查「候选列表里有哪两条」，不碰真实文件系统：路径在不同机器上不一定存在。
+func TestLLMBaseCoversBothVenvLayouts(t *testing.T) {
+	// 与 npm/install.js 的 venvDir() 保持一致：
+	//   process.platform === "win32" ? "Scripts" : "bin"
+	want := map[string]bool{
+		"~/.llm-venv/Scripts/llm.exe": false, // Windows
+		"~/.llm-venv/bin/llm":         false, // Unix
+	}
+	for _, c := range llmBase.candidates {
+		if _, ok := want[c]; ok {
+			want[c] = true
+		}
+	}
+	for c, found := range want {
+		if !found {
+			t.Errorf("llmBase.candidates 缺少 %q —— 另一个平台的 venv 布局会探测不到", c)
+		}
+	}
+}
+
 /* ── 引擎版本读取（2026-09-23）──
  * 用户：「引擎检测除了 a2a 的 其他也要支持有升级」—— 版本号是「升级」可验证的前提
  * （重探一次比对旧新，才能如实说「已升级」或「版本未变」）。 */

package/internal/agent/engine_test.go

@@ -155,6 +155,62 @@ func TestClaudePassesModelFlag(t *testing.T) {
 	}
 }
 
+// TestReasoningEffortArgs 推理档位（--reasoning，默认 max）到各引擎参数的映射：
+// claude/codebuddy 走 --effort，codex 走 -c model_reasoning_effort；空串 = 不传。
+func TestReasoningEffortArgs(t *testing.T) {
+	hasPair := func(args []string, k, v string) bool {
+		for i := 0; i+1 < len(args); i++ {
+			if args[i] == k && args[i+1] == v {
+				return true
+			}
+		}
+		return false
+	}
+
+	claudeArgs := (&ClaudeEngine{}).buildArgsBase(Request{Reasoning: "max"})
+	if !hasPair(claudeArgs, "--effort", "max") {
+		t.Errorf("claude --effort max 未透传: %v", claudeArgs)
+	}
+	// claude 不认 minimal，必须降级为 low，否则整轮被 clap 拒绝。
+	claudeMin := (&ClaudeEngine{}).buildArgsBase(Request{Reasoning: "minimal"})
+	if !hasPair(claudeMin, "--effort", "low") {
+		t.Errorf("claude minimal 应降级 low: %v", claudeMin)
+	}
+	if got := (&ClaudeEngine{}).buildArgsBase(Request{}); hasPair(got, "--effort", "max") {
+		t.Errorf("Reasoning 为空时不应追加 --effort: %v", got)
+	}
+
+	cbArgs := (&CodeBuddyEngine{}).buildArgsBase(Request{Reasoning: "xhigh"})
+	if !hasPair(cbArgs, "--effort", "xhigh") {
+		t.Errorf("codebuddy --effort xhigh 未透传: %v", cbArgs)
+	}
+
+	codexArgs := (&CodexEngine{}).buildArgs(Request{Reasoning: "max"}, "hi", "", "")
+	if !hasPair(codexArgs, "-c", `model_reasoning_effort="max"`) {
+		t.Errorf("codex model_reasoning_effort 未透传: %v", codexArgs)
+	}
+
+	// off/none/disabled 一律归一为「不传」。
+	for _, v := range []string{"off", "none", "disabled", " OFF "} {
+		if lv := ReasoningLevel(v); lv != "" {
+			t.Errorf("ReasoningLevel(%q) = %q, want \"\"", v, lv)
+		}
+	}
+	if ValidReasoningLevel("ultra") {
+		t.Error("ValidReasoningLevel(ultra) 应为 false")
+	}
+	for _, e := range []string{"claude", "codebuddy", "codebuddy-ai", "codex"} {
+		if !ReasoningSupportOf(e) {
+			t.Errorf("ReasoningSupportOf(%s) 应为 true", e)
+		}
+	}
+	for _, e := range []string{"trae", "llm", "openclaw", "dsh", "arkclaw"} {
+		if ReasoningSupportOf(e) {
+			t.Errorf("ReasoningSupportOf(%s) 应为 false", e)
+		}
+	}
+}
+
 func TestClaudeErrorEnvelope(t *testing.T) {
 	cli := writeFakeCLI(t, "claude", `#!/bin/sh
 echo '{"type":"result","subtype":"error_max_turns","is_error":true,"result":"超出轮次"}'
@@ -213,6 +269,51 @@ echo '{"type":"result","is_error":false,"result":"你好，世界"}'
 	}
 }
 
+// 「协议没跑完」的错误必须带上 CLI 的 stderr 尾巴（2026-10-09）。
+//
+// 用户报障截图里整条错误只有一句「codebuddy-ai CLI stream ended without result line」，
+// 而真正原因（CLI 崩了 / 鉴权或额度失败）几乎只出现在它自己的 stderr 里 ——
+// 不带出来就无从下手。这条错误也要求 CLI **exit 0 但没吐 result 行**
+// （非零退出走的是 wrapCliError 那条路）。
+func TestStreamNoResultLineCarriesStderr(t *testing.T) {
+	t.Run("codebuddy", func(t *testing.T) {
+		cli := writeFakeCLI(t, "codebuddy", `#!/bin/sh
+cat >/dev/null
+echo '{"type":"system","subtype":"init"}'
+echo 'Error: 401 unauthorized, api key invalid' >&2
+exit 0
+`)
+		_, err := (&CodeBuddyEngine{BinPath: cli}).Complete(context.Background(), Request{
+			Messages: []Message{{Role: "user", Content: "hi"}},
+		})
+		if err == nil {
+			t.Fatal("没见到 result 行必须报错")
+		}
+		if !strings.Contains(err.Error(), "stream ended without result line") ||
+			!strings.Contains(err.Error(), "401 unauthorized") {
+			t.Errorf("错误应同时含「协议未跑完」与 stderr 原因，实得：%v", err)
+		}
+	})
+	t.Run("claude", func(t *testing.T) {
+		cli := writeFakeCLI(t, "claude", `#!/bin/sh
+cat >/dev/null
+echo '{"type":"system","subtype":"init"}'
+echo 'Error: rate limit exceeded' >&2
+exit 0
+`)
+		_, err := (&ClaudeEngine{BinPath: cli}).Complete(context.Background(), Request{
+			Messages: []Message{{Role: "user", Content: "hi"}},
+		})
+		if err == nil {
+			t.Fatal("没见到 result 行必须报错")
+		}
+		if !strings.Contains(err.Error(), "stream ended without result line") ||
+			!strings.Contains(err.Error(), "rate limit exceeded") {
+			t.Errorf("错误应同时含「协议未跑完」与 stderr 原因，实得：%v", err)
+		}
+	})
+}
+
 func TestCodeBuddyArrayEnvelope(t *testing.T) {
 	cli := writeFakeCLI(t, "codebuddy", `#!/bin/sh
 echo '[{"type":"system","subtype":"init"},{"type":"assistant","message":{"content":[{"type":"text","text":"部分1"}]}},{"type":"result","result":"最终答案"}]'

package/internal/agent/env.go

@@ -29,6 +29,46 @@ import (
 // 不继承该前缀；CLI 不需要、也不应该绑定父进程的服务端口。
 const serverEnvPrefix = "SERVER__"
 
+// codebuddyEnvPrefix / claudeEnvPrefix 剔除的前缀：宿主 IDE（WorkBuddy）注入
+// 的大批 *_API_KEY / *_BUILTIN_SKILLS_DIR / *_GATEWAY_PASSWORD / *_PROJECT_DIR
+// / *_QIMEI36 / *_SAFE_DELETE_BULK_* 之类环境变量。
+//
+// ⚠️ 2026-10-01 实测：宿主的 CODEBUDDY_MCP_CONFIG 是合法 JSON，但下面这种
+// 配置组合会让 claude CLI 启动时 parse settings 失败、**直接 exit 0、零输出**：
+//
+//	--tools default（开工具）
+//	--permission-mode bypassPermissions
+//	--settings '{"sandbox":{"enabled":false}}'
+//	CODEBUDDY_MCP_CONFIG='{"mcpServers":...}'（宿主注入）
+//	CODEBUDDY_DISABLE_* / CODEBUDDY_PLUGIN_* / CLAUDE_PLUGIN_*（宿主注入）
+//
+// 表现为：「已完成 5892ms」但 AI 气泡空白，turn_failed 流。
+//
+// 修法（实测有效）：**一刀切**剥掉所有 CODEBUDDY_* 与 CLAUDE_* 变量再下传。
+// magic-agent 自己的鉴权走显式 API key（不靠 env），子 CLI 不再依赖任何
+// 宿主 IDE 状态；缺哪些值再由调用方按需通过 extraEnv 注入。
+const codebuddyEnvPrefix = "CODEBUDDY_"
+const claudeEnvPrefix = "CLAUDE_"
+
+// baggagePrefix / bashFuncPrefix / bashEnvName 剔除的**精确名字**：
+//
+//	BAGGAGE=codebuddy.session_id=...   —— WorkBuddy shell runtime 注入；key 不是
+//	                                        CODEBUDDY_* 前缀，但值里嵌了 codebuddy 状态，
+//	                                        留着也无用且会让 claude 误读
+//	BASH_FUNC_*（rm / rmdir / unlink 等）—— Bash 函数导出，**专门**为 WorkBuddy
+//	                                       的「safe delete」shim 用；其他 CLI 进程用不到，
+//	                                       且函数体会把这些命令变成请求 safe-delete 守护，
+//	                                       大概率破坏子进程工具调用
+//	BASH_ENV=...shim/shell-runtime-bash-env.sh  —— bash 启动源文件；非 bash 进程不读
+//
+// 2026-10-01 实测：删了 BAGGAGE + BASH_FUNC_* + BASH_ENV 后，claude CLI 的
+// 「Invalid JSON provided to --settings」错误从子进程 stderr 里消失，
+// 流式输出恢复正常。
+const (
+	baggageName = "BAGGAGE"
+	bashEnvName = "BASH_ENV"
+)
+
 // envDenylist 精确剔除的变量名（前缀规则之外的部分）。
 var envDenylist = map[string]bool{
 	// 父会话的会话/请求标识：子进程复用会让 CLI 误以为自己是既有会话
@@ -46,6 +86,22 @@ var envDenylist = map[string]bool{
 	// venv 自带隔离，不需要宿主注入；node 系 CLI（claude/codebuddy/trae）不受影响。
 	"PYTHONHOME": true,
 	"PYTHONPATH": true,
+
+	// 宿主 IDE / workbuddy 注入（2026-10-01 实测）：
+	//   - CLAUDE_PLUGIN_* / CODEBUDDY_PLUGIN_* —— IDE 自己的 hook 注入，引擎读不到也不该读
+	//   - CODEBUDDY_MCP_CONFIG —— 大段 mcpServers JSON。claude CLI 启动时会把它当自己的
+	//     settings 试图解析，**直接报「Invalid JSON provided to --settings」、exit 0
+	//     零输出**。表现：magic-agent --stream --events 一句话都拿不到，用户看到
+	//     「已完成 5892ms」但 AI 气泡空白。剥掉这条是当前唯一不需要改 claude CLI 的修法。
+	//   - CODEBUDDY_DISABLE_* —— IDE 注入的「关掉某些特性」开关；claude CLI 读不懂
+	//     容易误动作，剥掉。
+	//   - CODEBUDDY_CONFIG_DIR / CODEBUDDY_CODE_IMAGE_COMPRESSION_MAX_DIMENSION /
+	//     CODEBUDDY_SAFE_DELETE_BULK_GUARD —— 宿主配置/沙箱细节，claude/codebuddy
+	//     不需要。
+	"CODEBUDDY_MCP_CONFIG":                           true,
+	"CODEBUDDY_CONFIG_DIR":                           true,
+	"CODEBUDDY_CODE_IMAGE_COMPRESSION_MAX_DIMENSION": true,
+	"CODEBUDDY_SAFE_DELETE_BULK_GUARD":               true,
 }
 
 // environ 返回供子 CLI 继承的环境变量（已剔除父进程专属项）。
@@ -89,7 +145,19 @@ func ChildEnvWith(extraEnv []string) []string {
 // 不会少剔除，故这里两个平台统一按大写比较。
 func envDenied(name string) bool {
 	upper := strings.ToUpper(name)
-	if strings.HasPrefix(upper, serverEnvPrefix) {
+	// 新增的 CODEBUDDY_* / CLAUDE_* 前缀同样按大写比较：Windows 上环境变量名
+	// 本身不区分大小写，逐字符比较会漏剔除（同 serverEnvPrefix 的教训）。
+	switch {
+	case strings.HasPrefix(upper, serverEnvPrefix),
+		strings.HasPrefix(upper, codebuddyEnvPrefix),
+		strings.HasPrefix(upper, claudeEnvPrefix):
+		return true
+	}
+	if upper == baggageName || upper == bashEnvName {
+		return true
+	}
+	// BASH_FUNC_* —— WorkBuddy 的 safe-delete shim 注入。
+	if strings.HasPrefix(upper, "BASH_FUNC_") {
 		return true
 	}
 	return envDenylist[upper]

package/internal/agent/itemtracker.go

@@ -0,0 +1,271 @@
+package agent
+
+// itemtracker.go - 状态收敛的可复用跟踪器（2026-10-02）。
+//
+// streamAccumulator 内嵌了一份状态收敛逻辑，但那只覆盖走
+// `streamAccumulator` 的三个引擎（claude / codebuddy / trae）。
+// 其余六个引擎组各有自己的累加器结构与 emit 路径：
+//
+//	codex                  codexStreamAcc
+//	llm                    thinkSplitter
+//	openclaw               acpStreamState
+//	dsh / dsh_sdk          各自的 session.event 帧循环（同一引擎两条协议路径）
+//	arkclaw                SSE 两帧（整段到达）
+//	codebuddy-gateway      SSE 单帧（整段到达）
+//
+// 让它们各自造一套 id/revision 逻辑必然漂移，所以把**与引擎无关的部分**
+// （item 身份、revision 计数、状态机）抽成本文件，各引擎持有一个实例。
+//
+// 分工边界（重要）：
+//   itemTracker  —— 身份与版本：item id、revision 递增、status 语义
+//   调用方        —— 内容累积：claude 要按 content block index 升序拼接，
+//                    别的引擎直接 append 或整段替换
+//
+// 两个累积入口对应两种真实协议形态：
+//   Append(delta)  增量协议（claude delta / trae delta.content / llm chunk）
+//   Replace(full)  整段协议（arkclaw 与 gateway 一次给全文）——语义是
+//                  **替换不是追加**，追加会得到「你好你好」
+
+import "fmt"
+
+// itemLane 同一轮内并行的内容通道。
+//
+// 为什么按 lane 拆开 item（2026-10-02 修正）：
+// thinking 与 text 共享一个 item id 时，消费方按 (item_id, revision)
+// 覆盖式 upsert 会**丢掉先到的那一半**——
+//
+//	thinking(snapshot=「我在想」, rev=1)
+//	text    (snapshot=「答案」,   rev=2)   ← 覆盖，思考消失
+//
+// Text 字段是增量，所以终端直打完全看不出来；出问题的是走 snapshot
+// 的消费方（历史回放、多端同步）—— 思考内容静默消失，且没有任何报错。
+//
+// agents-anywhere 面对同一问题选了同样的方向：reasoning 是**独立的
+// system item**（runtime_protocol/timeline.py 的 SystemContentKind =
+// "reasoning"），与 message 分属不同 TimelineItemType，压根不共用 item。
+//
+// 拆开不丢关联性：两个 item id 内嵌**同一个原生 message id**
+// （claude_msg_<id> 与 claude_think_<id>），消费方要合并展示时
+// 按原生 id 关联即可，不需要额外的映射表。
+type itemLane string
+
+const (
+	// laneText 正文通道，item id 形如 claude_msg_<native>。
+	laneText itemLane = ""
+
+	// laneThink 思考/推理通道，item id 形如 claude_think_<native>。
+	// 中段用 think_（不是 reason_）：与 wire 上的事件 type=thinking 对齐，
+	// 读日志/grep 时不用在 reason / think / reasoning 之间猜。
+	laneThink itemLane = "think_"
+)
+
+// itemAttrs 一条事件的收敛属性。apply 把它写回 StreamEvent。
+type itemAttrs struct {
+	ItemID   string
+	Revision uint64
+	Status   StreamStatus
+	Snapshot string
+}
+
+// apply 把收敛属性挂到事件上。
+func (a itemAttrs) apply(ev *StreamEvent) {
+	ev.ItemID = a.ItemID
+	ev.ItemRevision = a.Revision
+	ev.Status = a.Status
+	ev.Snapshot = a.Snapshot
+}
+
+// itemTracker 维护「本轮当前 item」的身份与版本。
+//
+// 零值不可用，必须用 newItemTracker 构造。生命周期与一轮流式调用一致
+// （每轮新建），所以不需要显式释放。
+type itemTracker struct {
+	prefix   string
+	itemID   string
+	nativeID string
+	revision uint64
+	snapshot []byte
+	// localSeq 无原生 id 时的降级序号，**只增不减**。
+	//
+	// 为什么不复用 revision：revision 会被 Begin 归零，于是同一跟踪器里的
+	// 两条无 id 消息都会拿到 local_1 —— 后一条覆盖前一条（症状同
+	// 「一轮多条 assistant message 只剩最后一段」）。序号必须跨 Begin 单调。
+	localSeq uint64
+}
+
+// newItemTracker 构造某条 lane 的跟踪器。engine 决定 item id 前缀，
+// lane 决定中段（不同引擎的原生 id 空间不互通，混用会让跨引擎回放撞 id）。
+func newItemTracker(engine string, lane itemLane) *itemTracker {
+	return &itemTracker{prefix: itemTrackerPrefix(engine, lane)}
+}
+
+// itemTrackerPrefix 该引擎 + lane 的 item id 前缀。
+func itemTrackerPrefix(engine string, lane itemLane) string {
+	base := "msg_"
+	if engine != "" {
+		base = engine + "_" + base
+	}
+	if lane == laneText {
+		return base
+	}
+	// 非正文通道插在中段：claude_msg_ → claude_think_
+	return engine + "_" + string(lane) + "msg_"
+}
+
+// Begin 声明「一条新消息开始了」。
+//
+// 什么时候必须调：claude 一轮里可能有**多条** assistant message
+// （工具调用后继续对话，每次 tool_result 之后都是新的 message_start）。
+// 若不切，一轮里的多条消息会共用一个 item id —— 前一条被后一条覆盖，
+// 症状是「对话里只有最后一段回复，前面的不见了」。
+//
+// agents-anywhere 在 message_start 里 clear() 块桶并把 revision 归零
+// （runtimes/claude/timeline/stream.py:35-36），本方法是对同一动作的封装。
+//
+// nativeID 为空时按序号降级（协议没给 message id）。
+//
+// 重复调用是安全的：带**同一个** native id 再 Begin 视为无操作，
+// 不会清掉已累积的内容。某些实现在一条消息里会重复吐 message_start
+// （codebuddy 实测有），照单重开会凭空截断正文。
+func (t *itemTracker) Begin(nativeID string) {
+	if nativeID != "" && nativeID == t.nativeID {
+		return
+	}
+	t.itemID = ""
+	t.nativeID = nativeID
+	t.revision = 0
+	t.snapshot = t.snapshot[:0]
+	if nativeID != "" {
+		t.itemID = t.prefix + nativeID
+	}
+}
+
+// Note 记住引擎原生 id（拿不到就不给 item id——**不猜**）。
+//
+// 必须在第一个内容事件**之前**调：id 是先于内容出现的
+// （claude 的 message_start、codex 的 item.started）。
+// 之后仍可补记，届时会把已建立的降级 id 升级为原生形式。
+func (t *itemTracker) Note(nativeID string) {
+	if nativeID == "" || t.nativeID == nativeID {
+		return
+	}
+	t.nativeID = nativeID
+	// 只在本轮还没发出任何事件时升级 item id：已经发过的帧挂在
+	// 降级 id 上，中途换 id 看起来像丢内容（消费方按 id 建表）。
+	if t.revision == 0 {
+		t.itemID = t.prefix + nativeID
+	}
+}
+
+// ensure 建立 item id（降级链见上：原生 id → 本轮内稳定序号）。
+//
+// 序号取自 localSeq（**不**取自 revision）：revision 会被 Begin 归零，
+// 拿它当序号会让同一跟踪器里的两条无 id 消息撞成同一个 local_1，
+// 后一条把前一条覆盖掉。
+func (t *itemTracker) ensure() string {
+	if t.itemID != "" {
+		return t.itemID
+	}
+	t.localSeq++
+	t.itemID = fmt.Sprintf("%slocal_%d", t.prefix, t.localSeq)
+	return t.itemID
+}
+
+// next 取下一个 revision 并返回收敛属性。
+func (t *itemTracker) next(status StreamStatus) itemAttrs {
+	return t.nextWith(status, string(t.snapshot))
+}
+
+// nextWith 同 next，但调用方自己提供 snapshot 内容。
+//
+// 存在的理由：claude 的 snapshot 必须按 content block index 升序拼接
+// （到达顺序不等于 index 顺序），由 streamAccumulator 算好后传进来 ——
+// 身份与版本仍由跟踪器统一管理，内容拼接留给调用方（见文件头分工边界）。
+func (t *itemTracker) nextWith(status StreamStatus, snapshot string) itemAttrs {
+	t.revision++
+	return itemAttrs{
+		ItemID:   t.ensure(),
+		Revision: t.revision,
+		Status:   status,
+		Snapshot: snapshot,
+	}
+}
+
+// Append 累积一段增量，返回该 item 的新版本属性（status=running）。
+//
+// 用于**增量协议**引擎：每帧把 delta 拼上去，snapshot 始终是累积整段。
+func (t *itemTracker) Append(delta string) itemAttrs {
+	if delta != "" {
+		t.snapshot = append(t.snapshot, delta...)
+	}
+	return t.next(StatusRunning)
+}
+
+// Replace 用整段替换累积内容，返回新版本属性（status=running）。
+//
+// 用于**整段协议**引擎（arkclaw / codebuddy-gateway 一次给全文）。
+// 语义必须是替换：这些引擎每帧给的是全文，追加会让同一份内容数两遍。
+func (t *itemTracker) Replace(full string) itemAttrs {
+	t.snapshot = append(t.snapshot[:0], full...)
+	return t.next(StatusRunning)
+}
+
+// Finalize 收尾：把权威正文（引擎的 result 行）作为最后版本（status=final）。
+//
+// snapshot 用引擎给的权威值而非累积值 —— 增量拼接与 result 偶有出入
+// （codebuddy 还要过 think 剥离）时以 result 为准。
+//
+// 没有建立过 item 时返回 ok=false：不该为「一句正文都没流出来」的轮次硬造 item。
+func (t *itemTracker) Finalize(final string) (itemAttrs, bool) {
+	if t.itemID == "" {
+		return itemAttrs{}, false
+	}
+	if final != "" {
+		t.snapshot = append(t.snapshot[:0], final...)
+		return t.next(StatusFinal), true
+	}
+	// 没给权威值就沿用累积值，别把已有内容清空。
+	return t.next(StatusFinal), true
+}
+
+// Failed 异常收尾（status=failed）：引擎流被截断，没走到终帧。
+//
+// 挂到已有 item 上：内容还在，只是这条 item 不会再增长。消费方看到
+// failed 就知道不必再等。没建立过 item 时返回 ok=false。
+//
+// snapshot 形参用于 claude 那类「内容由调用方按 block 拼」的引擎 ——
+// 跟踪器自己累积的那份是空的，传空串即可回退到它。
+func (t *itemTracker) Failed(snapshot string) (itemAttrs, bool) {
+	if t.itemID == "" {
+		return itemAttrs{}, false
+	}
+	return t.nextWith(StatusFailed, snapshot), true
+}
+
+// trackerPair 是同一轮内并行的两条 lane 跟踪器。
+//
+// 单独这个类型是为了让「收尾」这类**跨 lane 操作**有一个明确归属。
+// 注意这里只提供 text lane 的终态 —— 思考 lane **不单独发终态**：
+//
+//   - final   ：result 行只含正文，给思考发 final 会让快照回退成空
+//   - failed  ：turn_failed 本身已是轮级终态信号
+//
+// 两条 lane 的终止由消费方「见到轮级终态后不再等思考」来表达，
+// 详见 stream.go emitTurnEnd / emitTurnFailed 的注释。
+type trackerPair struct {
+	text  *itemTracker
+	think *itemTracker
+}
+
+// finalize 收尾正文 lane（final 状态，权威值 = result 行的正文）。
+func (p trackerPair) finalize(final string) (itemAttrs, bool) {
+	return p.text.Finalize(final)
+}
+
+// failText 异常收尾正文 lane（failed 状态）。
+//
+// snapshot 形参由调用方提供：claude 的内容按 content block index 分桶
+// 累积在累加器里，跟踪器自己那份是空的。
+func (p trackerPair) failText(snapshot string) (itemAttrs, bool) {
+	return p.text.Failed(snapshot)
+}