magic-agent 1.0.0

package/internal/agent/env.go

@@ -0,0 +1,88 @@
+package agent
+
+// env.go - 子进程环境构造（darwin / linux / windows 通用）。
+//
+// 除继承当前环境（CLI 依赖 HOME/PATH 等基础变量）外，还要剔除若干
+// 「只能属于父进程」的变量。见 childEnvDenylist。
+
+import (
+	"os"
+	"strings"
+)
+
+// serverEnvPrefix 剔除的前缀：父会话内置 HTTP 服务的监听地址。
+//
+// WorkBuddy 父会话用 SERVER__HOST / SERVER__PORT（双下划线）把自身
+// 内置 HTTP 服务的监听端口注入给子进程。codebuddy CLI 读到这两个变量后
+// 会在**同一个端口**再起一个服务，撞上父进程已监听 → EADDRINUSE →
+// 启动流程里该错误是 unhandled rejection，CLI 既不退出也不产出任何
+// stdout/stderr，表现为**永久挂起**。
+//
+// 实测（2026-09-15）：
+//
+//	继承 SERVER__PORT=<父进程端口>   → 100s+ 无输出，必挂
+//	剔除 SERVER__PORT               → 4~9s 正常返回
+//	换成任意空闲端口                 → 正常返回
+//
+// 这是「在 WorkBuddy 会话里嵌套调用 codebuddy 引擎永远没结果」的根因，
+// 不是 CLI 本身的问题（干净环境下同一命令数秒即回）。因此子进程一律
+// 不继承该前缀；CLI 不需要、也不应该绑定父进程的服务端口。
+const serverEnvPrefix = "SERVER__"
+
+// envDenylist 精确剔除的变量名（前缀规则之外的部分）。
+var envDenylist = map[string]bool{
+	// 父会话的会话/请求标识：子进程复用会让 CLI 误以为自己是既有会话
+	// 的重入调用，可能串到父会话上下文，故一并剔除。
+	"CODEBUDDY_SESSION_ID":              true,
+	"CODEBUDDY_CONVERSATION_REQUEST_ID": true,
+	"CODEBUDDY_CONVERSATION_MESSAGE_ID": true,
+	"CODEBUDDY_TOOL_CALL_ID":            true,
+	"CLAUDE_SESSION_ID":                 true,
+
+	// Python 解释器路径注入：宿主环境（如 TRAE 会话）会把 PYTHONHOME 指到
+	// 自带的 Python.framework、PYTHONPATH 指到跨版本 site-packages。
+	// llm CLI 由 venv python 启动，读到这两个变量后 sys.path 错乱，
+	// 直接以 path 配置 dump / "<no Python frame>" 退出（实测 2026-09-16）。
+	// venv 自带隔离，不需要宿主注入；node 系 CLI（claude/codebuddy/trae）不受影响。
+	"PYTHONHOME": true,
+	"PYTHONPATH": true,
+}
+
+// environ 返回供子 CLI 继承的环境变量（已剔除父进程专属项）。
+func environ() []string {
+	src := os.Environ()
+	out := make([]string, 0, len(src))
+	for _, kv := range src {
+		name, _, ok := strings.Cut(kv, "=")
+		if !ok {
+			continue
+		}
+		if envDenied(name) {
+			continue
+		}
+		out = append(out, kv)
+	}
+	return out
+}
+
+// ChildEnvWith 返回「子进程应继承的环境（environ()，已剔除父进程专属项）」
+// 追加 extraEnv 后的结果。
+//
+// exec 对重复 key 取**后出现**的那份，所以 extraEnv 可以覆盖继承来的同名变量
+// —— 这正是账号隔离需要的语义（见 codebuddy.go 的 codebuddyAccountEnv）。
+// 交互式登录入口（--login）也用它构造环境，保证与普通调用同源。
+func ChildEnvWith(extraEnv []string) []string {
+	if len(extraEnv) == 0 {
+		return environ()
+	}
+	out := environ()
+	return append(out, extraEnv...)
+}
+
+// envDenied 判断某环境变量是否不允许传给子 CLI。
+func envDenied(name string) bool {
+	if strings.HasPrefix(name, serverEnvPrefix) {
+		return true
+	}
+	return envDenylist[name]
+}

package/internal/agent/env_test.go

@@ -0,0 +1,106 @@
+//go:build !windows
+
+package agent
+
+// env_test.go - 子进程环境剔除规则回归测试。
+//
+// 背景：WorkBuddy 父会话把 SERVER__PORT 注入给子进程，codebuddy CLI
+// 会用该端口再起一个服务，撞上父进程已监听 → EADDRINUSE → 永久挂起。
+// 本文件锁定「SERVER__ 前缀必须被剔除」这一行为，防止回归。
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestEnvironStripsServerPrefix(t *testing.T) {
+	t.Setenv("SERVER__PORT", "58311")
+	t.Setenv("SERVER__HOST", "127.0.0.1")
+
+	for _, kv := range environ() {
+		name, _, _ := strings.Cut(kv, "=")
+		if strings.HasPrefix(name, "SERVER__") {
+			t.Errorf("SERVER__* 不应传给子 CLI，但出现: %s", kv)
+		}
+	}
+}
+
+func TestEnvironStripsParentSessionIDs(t *testing.T) {
+	denied := []string{
+		"CODEBUDDY_SESSION_ID",
+		"CODEBUDDY_CONVERSATION_REQUEST_ID",
+		"CODEBUDDY_CONVERSATION_MESSAGE_ID",
+		"CODEBUDDY_TOOL_CALL_ID",
+		"CLAUDE_SESSION_ID",
+	}
+	for _, k := range denied {
+		t.Setenv(k, "test-value")
+	}
+
+	got := map[string]bool{}
+	for _, kv := range environ() {
+		name, _, _ := strings.Cut(kv, "=")
+		got[name] = true
+	}
+	for _, k := range denied {
+		if got[k] {
+			t.Errorf("父会话标识 %s 不应传子 CLI", k)
+		}
+	}
+}
+
+// 基础变量必须保留：CLI 依赖 HOME/PATH，剔多了会直接跑不起来。
+func TestEnvironKeepsEssentials(t *testing.T) {
+	t.Setenv("MAGIC_AGENT_TEST_KEEP", "yes")
+	got := map[string]bool{}
+	for _, kv := range environ() {
+		name, _, _ := strings.Cut(kv, "=")
+		got[name] = true
+	}
+	for _, k := range []string{"HOME", "PATH", "MAGIC_AGENT_TEST_KEEP"} {
+		if !got[k] {
+			t.Errorf("基础变量 %s 被误剔除", k)
+		}
+	}
+	if _, ok := os.LookupEnv("HOME"); ok && !got["HOME"] {
+		t.Error("HOME 必须传递")
+	}
+}
+
+// 宿主注入的 Python 变量必须剔除：llm 引擎由 venv python 启动，
+// PYTHONHOME / PYTHONPATH 会打乱其 sys.path（见 env.go 注释）。
+func TestEnvironStripsPythonVars(t *testing.T) {
+	t.Setenv("PYTHONHOME", "/some/host/python")
+	t.Setenv("PYTHONPATH", "/some/host/site-packages")
+
+	got := map[string]bool{}
+	for _, kv := range environ() {
+		name, _, _ := strings.Cut(kv, "=")
+		got[name] = true
+	}
+	for _, k := range []string{"PYTHONHOME", "PYTHONPATH"} {
+		if got[k] {
+			t.Errorf("%s 不应传给子 CLI（会破坏 llm 的 venv 解释器）", k)
+		}
+	}
+}
+
+func TestEnvDenied(t *testing.T) {
+	cases := map[string]bool{
+		"SERVER__PORT":                true,
+		"SERVER__HOST":                true,
+		"SERVER__ANYTHING":            true,
+		"CODEBUDDY_SESSION_ID":        true,
+		"CODEBUDDY_SERVICE_PROXY_URL": false, // 保留：CLI 可能依赖父会话服务
+		"CODEBUDDY_MCP_CONFIG":        false,
+		"HOME":                        false,
+		"PATH":                        false,
+		"CODEBUDDY_CONFIG_DIR":        false,
+	}
+	for name, want := range cases {
+		if got := envDenied(name); got != want {
+			t.Errorf("envDenied(%q) = %v, want %v", name, got, want)
+		}
+	}
+}

package/internal/agent/jsonextract.go

@@ -0,0 +1,128 @@
+package agent
+
+// jsonextract.go - llm 引擎的结构化输出后处理。
+//
+// 背景：上游（magic-video）注入 JSON Schema 进 system prompt，要求模型按
+// schema 一次性输出 JSON 对象。llm CLI 走 OpenAI-compatible chat/completions
+// 后返回的 `<response>` 是字符串；模型常把 JSON 嵌套进 `<think>...</think>`
+// 之外的纯文本里，有时还裹了 markdown 围栏（```json ... ```）。直接拿原始
+// 文本会让上游 `json.Unmarshal` 失败。
+//
+// `extractJSONObjectStrict` 用 schema 提供的「顶层必填字段」作为硬判定：
+//   1. 必须能从文本里找到一个 JSON 对象（容忍 ```json 围栏与前后废话）；
+//   2. 解出的对象必须是 map[string]any，且所有 schema.Required 都出现在
+//      顶层键里（缺一个就算失败，不兜底）；
+//   3. type=object 才执行；其他 schema 类型当前项目不出现。
+//
+// 失败时不改写原文本，让上游解析器（base/score 等已有 json 围栏剥离逻辑）
+// 走兜底。
+//
+// 这条路径只对 llm 引擎启用。其他引擎（codebuddy/trae/claude）通过
+// `--json-schema` flag / 各引擎自带的结构化输出支持处理；它们不进来。
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// extractJSONObjectStrict 尝试从 text 里抽出一个严格匹配 schema 顶层
+// Required 字段集的 JSON 对象，并返回紧凑 re-marshal 后的字符串。
+//
+// 失败时返回 (text, false) —— 调用方应原样用 text，不阻断。
+func extractJSONObjectStrict(text string, schema *JSONSchema) (string, bool) {
+	if schema == nil || !strings.EqualFold(schema.Type, "object") {
+		return text, false
+	}
+	if len(schema.Required) == 0 {
+		// 没有必填字段 → 不做"严格"判定，避免误判任何对象。
+		// 上游有自带的宽松解析（容忍围栏），走兜底即可。
+		return text, false
+	}
+
+	raw := strings.TrimSpace(text)
+	raw = stripJSONFence(raw)
+
+	obj, ok := firstJSONObject(raw)
+	if !ok {
+		return text, false
+	}
+
+	// 严格匹配：schema 顶层 Required 的每个字段都必须出现在 obj 的顶层键里。
+	// 注意：只用 m[k] 直接判定；若 model 把字段放在嵌套对象里（如
+	// {"scores": {...}}）也不通过 —— 上游要的就是扁平字段。
+	missing := make([]string, 0, len(schema.Required))
+	for _, k := range schema.Required {
+		if _, ok := obj[k]; !ok {
+			missing = append(missing, k)
+		}
+	}
+	if len(missing) > 0 {
+		return text, false
+	}
+
+	out, err := json.Marshal(obj)
+	if err != nil {
+		return text, false
+	}
+	return string(out), true
+}
+
+// stripJSONFence 去掉 markdown 的 ```json ... ``` 围栏（首尾）。
+func stripJSONFence(s string) string {
+	if !strings.HasPrefix(s, "```") {
+		return s
+	}
+	if idx := strings.Index(s, "\n"); idx > 0 {
+		s = s[idx+1:]
+	}
+	if end := strings.LastIndex(s, "```"); end > 0 {
+		s = s[:end]
+	}
+	return strings.TrimSpace(s)
+}
+
+// firstJSONObject 在 s 中找首个「完整」的顶层 JSON 对象，并解为 map。
+// 括号计数法（支持嵌套）。找到返回 (map, true)；未找到 (nil, false)。
+func firstJSONObject(s string) (map[string]any, bool) {
+	start := strings.IndexByte(s, '{')
+	if start < 0 {
+		return nil, false
+	}
+	depth, inStr, escape := 0, false, false
+	for i := start; i < len(s); i++ {
+		c := s[i]
+		if inStr {
+			switch c {
+			case '\\':
+				escape = !escape
+				continue
+			case '"':
+				if !escape {
+					inStr = false
+				}
+				escape = false
+				continue
+			default:
+				escape = false
+				continue
+			}
+		}
+		switch c {
+		case '"':
+			inStr = true
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				candidate := s[start : i+1]
+				var obj map[string]any
+				if err := json.Unmarshal([]byte(candidate), &obj); err != nil {
+					return nil, false
+				}
+				return obj, true
+			}
+		}
+	}
+	return nil, false
+}

package/internal/agent/jsonextract_test.go

@@ -0,0 +1,110 @@
+package agent
+
+// jsonextract_test.go - extractJSONObjectStrict 单元测试。
+//
+// 覆盖：
+//   - 普通 JSON 对象能抽取并紧凑化
+//   - 顶层缺 Required 字段 → 不改写
+//   - 围栏 / 前缀废话 → 剥掉
+//   - schema 为 nil / type 非 object / Required 为空 → 直接不动
+//   - 嵌套对象包了 Required 字段 → 不通过（要的就是扁平）
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// schemaRequired 构造只有 Required 的最小 schema（Properties 留空，不参与判定）。
+func schemaRequired(required ...string) *JSONSchema {
+	return &JSONSchema{Type: "object", Required: required}
+}
+
+func TestExtractJSONObjectStrict(t *testing.T) {
+	t.Run("plain object extract", func(t *testing.T) {
+		raw := `{"setting":12,"character":12,"issues":[]}`
+		got, ok := extractJSONObjectStrict(raw, schemaRequired("setting", "character", "issues"))
+		if !ok {
+			t.Fatal("ok=false on plain JSON")
+		}
+		// 应能紧凑 marshal 回 round-trip
+		var back map[string]any
+		if err := json.Unmarshal([]byte(got), &back); err != nil {
+			t.Fatalf("not valid JSON after extract: %v (got=%q)", err, got)
+		}
+		for _, k := range []string{"setting", "character", "issues"} {
+			if _, ok := back[k]; !ok {
+				t.Errorf("missing %q in extracted: %s", k, got)
+			}
+		}
+	})
+
+	t.Run("with markdown fence and prefix text", func(t *testing.T) {
+		raw := "Here is the result:\n```json\n{\"a\":1,\"b\":2}\n```"
+		got, ok := extractJSONObjectStrict(raw, schemaRequired("a", "b"))
+		if !ok {
+			t.Fatal("ok=false on fenced JSON")
+		}
+		var back map[string]any
+		if err := json.Unmarshal([]byte(got), &back); err != nil {
+			t.Fatalf("invalid: %v (got=%q)", err, got)
+		}
+	})
+
+	t.Run("missing required field rejects", func(t *testing.T) {
+		raw := `{"setting":12}`
+		got, ok := extractJSONObjectStrict(raw, schemaRequired("setting", "character"))
+		if ok {
+			t.Errorf("expected reject for missing required field, got ok=true text=%q", got)
+		}
+	})
+
+	t.Run("nested object with required key inside doesn't count", func(t *testing.T) {
+		raw := `{"scores":{"setting":12,"character":12}}` // Required 在嵌套层
+		got, ok := extractJSONObjectStrict(raw, schemaRequired("setting"))
+		if ok {
+			t.Errorf("nested field should not satisfy top-level Required, got ok=true text=%q", got)
+		}
+	})
+
+	t.Run("nil schema does nothing", func(t *testing.T) {
+		raw := `{"a":1}`
+		if got, ok := extractJSONObjectStrict(raw, nil); ok || got != raw {
+			t.Errorf("nil schema should not transform: got=%q ok=%v", got, ok)
+		}
+	})
+
+	t.Run("non-object schema type does nothing", func(t *testing.T) {
+		raw := `[1,2,3]`
+		s := &JSONSchema{Type: "array"}
+		if got, ok := extractJSONObjectStrict(raw, s); ok || got != raw {
+			t.Errorf("non-object schema should not transform: got=%q ok=%v", got, ok)
+		}
+	})
+
+	t.Run("empty Required does nothing (upstream parser handles leniently)", func(t *testing.T) {
+		raw := `{"a":1}`
+		s := &JSONSchema{Type: "object"} // Required == nil
+		if got, ok := extractJSONObjectStrict(raw, s); ok || got != raw {
+			t.Errorf("empty Required should not transform: got=%q ok=%v", got, ok)
+		}
+	})
+
+	t.Run("object with unicode keys and nested arrays", func(t *testing.T) {
+		raw := `{"setting":12,"issues":["a","b"],"suggestions":["x"]}`
+		got, ok := extractJSONObjectStrict(raw, schemaRequired("setting", "issues", "suggestions"))
+		if !ok {
+			t.Fatal("ok=false")
+		}
+		if !strings.Contains(got, `"issues":["a","b"]`) {
+			t.Errorf("nested array should be preserved: %s", got)
+		}
+	})
+
+	t.Run("no JSON object at all", func(t *testing.T) {
+		raw := "just some plain text answer"
+		if got, ok := extractJSONObjectStrict(raw, schemaRequired("a")); ok || got != raw {
+			t.Errorf("expected reject for no JSON: got=%q ok=%v", got, ok)
+		}
+	})
+}

package/internal/agent/keepalive_test.go

@@ -0,0 +1,216 @@
+package agent
+
+// keepalive_test.go - 常驻会话（Request.Append）在 claude/codebuddy 上的落地。
+//
+// 用户需求（2026-09-18）：「按路线 2 实现，先支持 claude 和 codebuddy 的追加功能」。
+//
+// 做法：假 CLI 用 `while read line` 模拟「stdin 每来一行就当作一轮」，
+// 把收到的每行长度回显成 result —— 于是可以断言：
+//   - 追加的消息**真的进了子进程的 stdin**（行数 = 1 + 追加数）；
+//   - 每轮都发 KindTurnEnd（CLI 的空闲收工挂在它上面）；
+//   - 关闭追加通道 → 子进程 EOF 收尾 → Stream 正常返回（不需要 --stop）。
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// multiTurnCLI 假 CLI：stdin 每来一行就回一个 result，并把该行追加写进 seenFile。
+func multiTurnCLI(t *testing.T, seenFile string) string {
+	t.Helper()
+	return writeFakeCLI(t, "claude", `#!/bin/sh
+while IFS= read -r line; do
+  printf '%s\n' "$line" >> `+seenFile+`
+  echo '{"type":"result","subtype":"success","is_error":false,"result":"ok","session_id":"s-ka","model":"m"}'
+done
+`)
+}
+
+// readLines 读 seenFile 的行数（文件可能还没建）。
+func readLines(t *testing.T, p string) []string {
+	t.Helper()
+	data, err := os.ReadFile(p)
+	if err != nil {
+		return nil
+	}
+	s := strings.TrimSpace(string(data))
+	if s == "" {
+		return nil
+	}
+	return strings.Split(s, "\n")
+}
+
+func TestKeepAliveAppendsReachChildStdin(t *testing.T) {
+	seen := filepath.Join(t.TempDir(), "seen.txt")
+	cli := multiTurnCLI(t, seen)
+	e := &ClaudeEngine{BinPath: cli}
+
+	appendCh := make(chan string, 4)
+	events, onEvent := collectEvents()
+
+	type res struct {
+		out StreamResult
+		err error
+	}
+	done := make(chan res, 1)
+	go func() {
+		out, err := e.Stream(context.Background(), Request{
+			Messages: []Message{{Role: "user", Content: "首轮任务"}},
+			Append:   appendCh,
+		}, onEvent)
+		done <- res{out, err}
+	}()
+
+	// 等首轮进了子进程
+	waitFor(t, func() bool { return len(readLines(t, seen)) >= 1 }, "首轮没进 stdin")
+	appendCh <- "追加需求 A"
+	waitFor(t, func() bool { return len(readLines(t, seen)) >= 2 }, "追加 A 没进 stdin")
+	appendCh <- "追加需求 B"
+	waitFor(t, func() bool { return len(readLines(t, seen)) >= 3 }, "追加 B 没进 stdin")
+
+	// 关闭通道 → 子进程 EOF → 优雅收尾
+	close(appendCh)
+
+	var got res
+	select {
+	case got = <-done:
+	case <-time.After(15 * time.Second):
+		t.Fatal("关闭追加通道后 Stream 没返回（常驻会话没能优雅收尾）")
+	}
+	if got.err != nil {
+		t.Fatalf("Stream: %v", got.err)
+	}
+	if got.out.Text != "ok" {
+		t.Errorf("Text = %q", got.out.Text)
+	}
+
+	lines := readLines(t, seen)
+	if len(lines) != 3 {
+		t.Fatalf("子进程收到 %d 行 want 3（首轮 + 两条追加）", len(lines))
+	}
+	if !strings.Contains(lines[0], "首轮任务") {
+		t.Errorf("第 1 行应是首轮提示词: %q", lines[0])
+	}
+	if !strings.Contains(lines[1], "追加需求 A") || !strings.Contains(lines[2], "追加需求 B") {
+		t.Errorf("追加内容没按顺序进 stdin: %v", lines)
+	}
+	// 追加是**流式输入**：每行都应是 user 消息 JSON
+	for i, l := range lines {
+		if !strings.Contains(l, `"type":"user"`) || !strings.Contains(l, `"role":"user"`) {
+			t.Errorf("第 %d 行不是 user 消息 JSON: %q", i+1, l)
+		}
+	}
+
+	// 每轮一个 KindTurnEnd（CLI 的空闲收工 / 应用侧「本轮完成」都靠它），且必须带会话 id
+	turnEnds := 0
+	for _, ev := range *events {
+		if ev.Kind == KindTurnEnd {
+			turnEnds++
+			if ev.SessionID != "s-ka" {
+				t.Errorf("turn_end 应带会话 id（应用侧靠它绑锚点），got %q", ev.SessionID)
+			}
+			if ev.Text == "" {
+				t.Error("turn_end 应带该轮正文")
+			}
+		}
+	}
+	if turnEnds != 3 {
+		t.Errorf("KindTurnEnd 事件数 = %d want 3（每轮一个）", turnEnds)
+	}
+}
+
+// codebuddy 同族，走同一条 stream-json 输入通道。
+func TestKeepAliveWorksForCodeBuddy(t *testing.T) {
+	seen := filepath.Join(t.TempDir(), "seen.txt")
+	cli := writeFakeCLI(t, "codebuddy", `#!/bin/sh
+while IFS= read -r line; do
+  printf '%s\n' "$line" >> `+seen+`
+  echo '{"type":"result","subtype":"success","is_error":false,"result":"ok","session_id":"s-ka","model":"m"}'
+done
+`)
+	e := &CodeBuddyEngine{BinPath: cli}
+	appendCh := make(chan string, 2)
+
+	done := make(chan error, 1)
+	go func() {
+		_, err := e.Stream(context.Background(), Request{
+			Messages: []Message{{Role: "user", Content: "首轮"}},
+			Append:   appendCh,
+		}, nil)
+		done <- err
+	}()
+	waitFor(t, func() bool { return len(readLines(t, seen)) >= 1 }, "首轮没进 stdin")
+	appendCh <- "追加到 codebuddy"
+	waitFor(t, func() bool { return len(readLines(t, seen)) >= 2 }, "追加没进 stdin")
+	close(appendCh)
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("Stream: %v", err)
+		}
+	case <-time.After(15 * time.Second):
+		t.Fatal("codebuddy 常驻会话没优雅收尾")
+	}
+	if lines := readLines(t, seen); !strings.Contains(strings.Join(lines, "\n"), "追加到 codebuddy") {
+		t.Errorf("追加内容没进 codebuddy 的 stdin: %v", lines)
+	}
+}
+
+func TestAppendSupportOf(t *testing.T) {
+	for engine, want := range map[string]bool{
+		"claude":       true,
+		"codebuddy":    true,
+		"codebuddy-ai": true,
+		// dsh：SDK 通道下对同一 sessionId 继续 session/prompt 即续接同一会话
+		//（官方 Python SDK 文档「reuse a harness, home, and id」）。
+		"dsh":      true,
+		"trae":     false,
+		"codex":    false,
+		"llm":      false,
+		"openclaw": false,
+		"arkclaw":  false,
+		"unknown":  false,
+	} {
+		if got := AppendSupportOf(engine); got != want {
+			t.Errorf("AppendSupportOf(%q) = %v want %v", engine, got, want)
+		}
+	}
+}
+
+// 常驻会话的**默认值**按引擎区分：claude/codebuddy 默认开，dsh 默认关（要显式 --keep-alive）。
+func TestAppendDefaultOn(t *testing.T) {
+	for engine, want := range map[string]bool{
+		"claude":       true,
+		"codebuddy":    true,
+		"codebuddy-ai": true,
+		"dsh":          false, // 显式 --keep-alive 才开
+		"trae":         false,
+		"unknown":      false,
+	} {
+		if got := AppendDefaultOn(engine); got != want {
+			t.Errorf("AppendDefaultOn(%q) = %v want %v", engine, got, want)
+		}
+	}
+	// 默认关的引擎也必须「支持」（否则显式 --keep-alive 会被能力表挡下）。
+	if !AppendSupportOf("dsh") || AppendDefaultOn("dsh") {
+		t.Error("dsh 应是「支持但默认关」")
+	}
+}
+
+// waitFor 轮询等待条件成立（最多 10s）。
+func waitFor(t *testing.T, cond func() bool, msg string) {
+	t.Helper()
+	deadline := time.Now().Add(10 * time.Second)
+	for time.Now().Before(deadline) {
+		if cond() {
+			return
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	t.Fatalf("超时：%s", msg)
+}