magic-agent 1.0.0

package/internal/cli/sessionlog_test.go

@@ -0,0 +1,262 @@
+package cli
+
+import (
+	"encoding/json"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestSessionWriterLazyOpenAndId 先 push 几条事件（无 session_id），再 setID，
+// 验证：(a) 没 id 时进 pending；(b) 有 id 后开文件并把 pending 也写进去。
+func TestSessionWriterLazyOpenAndId(t *testing.T) {
+	dir := t.TempDir()
+	sw := newSessionWriter(dir, 1)
+	defer sw.close()
+
+	sw.push(sessionEvent{Kind: "thinking", Text: "先想想"})
+	sw.push(sessionEvent{Kind: "tool_use", Text: `{"file":"a.go"}`, Name: "Read", ID: "t1"})
+
+	sw.setSessionID("sess-1")
+	sw.push(sessionEvent{Kind: "text", Text: "你好"})
+
+	drain(t, sw)
+
+	lines := readLines(t, filepath.Join(dir, "sess-1.jsonl"))
+	if len(lines) != 3 {
+		t.Fatalf("期望 3 行历史，实际 %d：%v", len(lines), lines)
+	}
+	var first, second, third sessionEvent
+	if err := json.Unmarshal([]byte(lines[0]), &first); err != nil {
+		t.Fatal(err)
+	}
+	if err := json.Unmarshal([]byte(lines[1]), &second); err != nil {
+		t.Fatal(err)
+	}
+	if err := json.Unmarshal([]byte(lines[2]), &third); err != nil {
+		t.Fatal(err)
+	}
+	if first.Kind != "thinking" || second.Kind != "tool_use" || third.Kind != "text" {
+		t.Fatalf("顺序不对：%s / %s / %s", first.Kind, second.Kind, third.Kind)
+	}
+	if third.SessionID != "sess-1" {
+		t.Fatalf("第三行应带 session_id=sess-1，实得 %q", third.SessionID)
+	}
+	if first.SessionID != "sess-1" {
+		t.Fatalf("pending 行回填 id 失败：%q", first.SessionID)
+	}
+	if first.Seq >= second.Seq || second.Seq >= third.Seq {
+		t.Fatalf("Seq 不单调：%d/%d/%d", first.Seq, second.Seq, third.Seq)
+	}
+}
+
+// TestSessionWriterFilePermissions 落盘文件权限 0600。
+func TestSessionWriterFilePermissions(t *testing.T) {
+	if os.Getuid() == 0 {
+		t.Skip("root 下 0600 检查无意义")
+	}
+	dir := t.TempDir()
+	sw := newSessionWriter(dir, 1)
+	sw.setSessionID("perm-1")
+	sw.push(sessionEvent{Kind: "text", Text: "你好"})
+	drain(t, sw)
+	st, err := os.Stat(filepath.Join(dir, "perm-1.jsonl"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if perm := st.Mode().Perm(); perm != 0o600 {
+		t.Fatalf("期望 0600 权限，实得 %v", perm)
+	}
+}
+
+// TestSessionWriterAppendMode 第二次开启相同 id 应在文件末尾续写，
+// 而不是覆盖 —— 续接同一会话时尤其重要（避免重复第一条事件）。
+func TestSessionWriterAppendMode(t *testing.T) {
+	dir := t.TempDir()
+	sw1 := newSessionWriter(dir, 1)
+	sw1.setSessionID("sess-X")
+	sw1.push(sessionEvent{Kind: "text", Text: "first"})
+	drain(t, sw1)
+	sw1.close()
+
+	sw2 := newSessionWriter(dir, 2)
+	sw2.setSessionID("sess-X")
+	sw2.push(sessionEvent{Kind: "text", Text: "second"})
+	drain(t, sw2)
+	sw2.close()
+
+	lines := readLines(t, filepath.Join(dir, "sess-X.jsonl"))
+	if len(lines) != 2 {
+		t.Fatalf("期望 2 行（不覆盖），实得 %d", len(lines))
+	}
+	var a, b sessionEvent
+	if err := json.Unmarshal([]byte(lines[0]), &a); err != nil {
+		t.Fatal(err)
+	}
+	if err := json.Unmarshal([]byte(lines[1]), &b); err != nil {
+		t.Fatal(err)
+	}
+	if a.Text != "first" || b.Text != "second" {
+		t.Fatalf("顺序或内容错：%q / %q", a.Text, b.Text)
+	}
+	if a.Seq < 1 || b.Seq < 1 {
+		t.Fatalf("Seq 至少从 1 起：a=%d b=%d", a.Seq, b.Seq)
+	}
+}
+
+// TestReadSessionLogMissing 没历史时不应 500 / 应返回 nil。
+func TestReadSessionLogMissing(t *testing.T) {
+	dir := t.TempDir()
+	cli := SessionLogDirOverride
+	defer func() { SessionLogDirOverride = cli }()
+	SessionLogDirOverride = dir
+	evs, err := ReadSessionLog("", "no-such-session")
+	if err != nil {
+		t.Fatalf("不存在的会话应该静默 OK：%v", err)
+	}
+	if evs != nil {
+		t.Fatalf("不存在的会话应该返回 nil：%v", evs)
+	}
+}
+
+// TestReadSessionLogSkipsCorruptLines 坏行不阻塞整体读取。
+func TestReadSessionLogSkipsCorruptLines(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "s.jsonl")
+	f, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, _ = f.WriteString(`{"seq":1,"kind":"text","text":"a","at":"2026-01-01T00:00:00Z","session_id":"s"}
+{not json
+{"seq":2,"kind":"text","text":"b","at":"2026-01-01T00:00:01Z","session_id":"s"}
+`)
+	_ = f.Close()
+	cli := SessionLogDirOverride
+	defer func() { SessionLogDirOverride = cli }()
+	SessionLogDirOverride = dir
+	evs, err := ReadSessionLog("", "s")
+	if err != nil {
+		t.Fatalf("读历史失败：%v", err)
+	}
+	if len(evs) != 2 {
+		t.Fatalf("坏行应跳过，剩 2 行，实际 %d", len(evs))
+	}
+	if evs[0].Text != "a" || evs[1].Text != "b" {
+		t.Fatalf("顺序错：%v", evs)
+	}
+}
+
+// TestSessionWriterRealisticStream 模拟「真实流」的写入模式：
+//   - 首条事件（带 init session_id）→ writer 拿到 id → 开文件 + 把 pending 写盘
+//   - 后续 thinking/text/tool_use/turn_end 都按时间顺序落盘
+//   - 文件按行追加；可被 ReadSessionLog 完整读回
+//
+// 关键不变量：流路径断掉（写盘慢）时 pending 不丢 id，open 完就立即 flush；
+// seq 单调递增；session_id 在 id 出现前后的行都能拿到。
+func TestSessionWriterRealisticStream(t *testing.T) {
+	dir := t.TempDir()
+	cli := SessionLogDirOverride
+	defer func() { SessionLogDirOverride = cli }()
+	SessionLogDirOverride = dir
+
+	sw, err := newSessionWriterAuto(sessionLogDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 模拟 handleNDJSONLine 的边写边喂：先 3 条无 id，再设 id（init），再 4 条。
+	sw.push(sessionEvent{Kind: "thinking", Text: "我应该"})
+	sw.push(sessionEvent{Kind: "thinking", Text: "回「收到」"})
+	sw.push(sessionEvent{Kind: "text", Text: "用户让我只回「收到」"})
+	sw.setSessionID("sess-real")
+	sw.push(sessionEvent{Kind: "text", Text: "收到"})
+	sw.push(sessionEvent{Kind: "tool_use", Name: "Read", ID: "t1", Text: `{"file":"x"}`})
+	sw.push(sessionEvent{Kind: "tool_result", ID: "t1", Text: "ok"})
+	sw.push(sessionEvent{Kind: "turn_end", Text: "收到"})
+
+	drain(t, sw)
+
+	lines := readLines(t, filepath.Join(dir, "sess-real.jsonl"))
+	if len(lines) != 7 {
+		t.Fatalf("期望 7 行，实得 %d：\n%v", len(lines), lines)
+	}
+
+	want := []string{"thinking", "thinking", "text", "text", "tool_use", "tool_result", "turn_end"}
+	for i, ln := range lines {
+		var ev sessionEvent
+		if err := json.Unmarshal([]byte(ln), &ev); err != nil {
+			t.Fatalf("line %d 解析失败: %v", i, err)
+		}
+		if ev.Kind != want[i] {
+			t.Fatalf("line %d: 期望 kind=%s 实得 %s", i, want[i], ev.Kind)
+		}
+		if ev.SessionID != "sess-real" {
+			t.Fatalf("line %d: 所有行都应带 session_id，实得 %q", i, ev.SessionID)
+		}
+		if i > 0 {
+			var prev sessionEvent
+			_ = json.Unmarshal([]byte(lines[i-1]), &prev)
+			if ev.Seq <= prev.Seq {
+				t.Fatalf("line %d: Seq 必须严格递增 a=%d b=%d", i, prev.Seq, ev.Seq)
+			}
+		}
+	}
+
+	// 反向验证 —— ReadSessionLog 能完整读回 7 条。
+	evs, err := ReadSessionLog("", "sess-real")
+	if err != nil {
+		t.Fatalf("ReadSessionLog 失败：%v", err)
+	}
+	if len(evs) != 7 {
+		t.Fatalf("ReadSessionLog 期望 7 条，实得 %d", len(evs))
+	}
+}
+
+// drain 等 writer 的 in 通道全部写完。close 之后再等它把所有 pending 全 flush。
+func drain(t *testing.T, sw *sessionWriter) {
+	t.Helper()
+	sw.close()
+}
+
+func readLines(t *testing.T, path string) []string {
+	t.Helper()
+	f, err := os.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer f.Close()
+	b, err := io.ReadAll(f)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(b) == 0 {
+		return nil
+	}
+	return strings.Split(strings.TrimRight(string(b), "\n"), "\n")
+}
+
+// 保留一个简单的并发 sanity：setID 与 push 并发调用，writer 不能崩。
+func TestSessionWriterConcurrentSetIDAndPush(t *testing.T) {
+	dir := t.TempDir()
+	sw := newSessionWriter(dir, 1)
+	var wg sync.WaitGroup
+	for i := 0; i < 50; i++ {
+		wg.Add(2)
+		go func(i int) {
+			defer wg.Done()
+			sw.setSessionID("id-" + string(rune('a'+i%26)))
+		}(i)
+		go func(i int) {
+			defer wg.Done()
+			sw.push(sessionEvent{Kind: "text", Text: "msg"})
+			time.Sleep(time.Millisecond)
+		}(i)
+	}
+	wg.Wait()
+	sw.close()
+}

package/internal/cli/sessionlog_user_test.go

@@ -0,0 +1,129 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// 用户提问落盘（kind:"user"）的端到端验证。
+//
+// 为什么值得一条端到端测试：这个 push 发生在 **session_id 还不知道**的时刻
+//（引擎要到流里才报 id），所以它落盘的正确性完全依赖 sessionWriter 的 pending 缓冲
+//「拿到 id 后先刷 pending、再写当前事件」这个顺序。单看代码容易以为要手动等 id ——
+// 一旦谁把它改成「等 id 再 push」，就会把流路径堵住（违反「绝不断流」），或者顺序错乱。
+//
+// 这一条钉住三件事：
+//  1. 用户提问**确实**落盘了（在此之前历史里只有 agent 的单方面发言）；
+//  2. 它是**第一条**（排在引擎事件之前 —— 证明 pending 被先刷出）；
+//  3. seq 从 1 起且严格递增（历史接口靠 seq 做游标，断了就续读不成）。
+
+// userEchoStreamEngine 模拟真实引擎：在流**开始时**报出 session_id（真实引擎在 init 行里报），
+// 然后发 thinking / text。这样 userEvent 的 push 必然早于 id 的出现。
+type userEchoStreamEngine struct {
+	name      string
+	sessionID string
+}
+
+func (e *userEchoStreamEngine) Name() string           { return e.name }
+func (e *userEchoStreamEngine) Detect() (bool, string) { return true, "fake://" + e.name }
+
+func (e *userEchoStreamEngine) Complete(_ context.Context, _ agent.Request) (agent.Response, error) {
+	return agent.Response{Text: "收到", Model: "fake-model"}, nil
+}
+
+func (e *userEchoStreamEngine) Stream(_ context.Context, req agent.Request, onEvent func(agent.StreamEvent)) (agent.StreamResult, error) {
+	// 引擎流里见到 session_id 的那一刻 —— 这是 writer 开文件的触发点。
+	if req.OnSessionID != nil {
+		req.OnSessionID(e.sessionID)
+	}
+	onEvent(agent.StreamEvent{Kind: agent.KindThinking, Text: "想一下"})
+	onEvent(agent.StreamEvent{Kind: agent.KindText, Text: "收到"})
+	return agent.StreamResult{
+		Response: agent.Response{Engine: e.name, Text: "收到", Model: "fake-model", SessionID: e.sessionID},
+	}, nil
+}
+
+func TestStreamAskPersistsUserMessage(t *testing.T) {
+	dir := t.TempDir()
+	prev := SessionLogDirOverride
+	SessionLogDirOverride = dir
+	defer func() { SessionLogDirOverride = prev }()
+
+	const sid = "sess-user-log"
+	const prompt = "帮我把 guard 的令牌比较改成常数时间，避免时序侧信道"
+	registerFake(&userEchoStreamEngine{name: "fake-user-log", sessionID: sid})
+
+	if _, _, err := runAskCmd(t, "", "-e", "fake-user-log", "--stream", prompt); err != nil {
+		t.Fatalf("--stream: %v", err)
+	}
+
+	// runStreamAsk 用 defer sessionLog.close() 收尾，所以命令返回后文件已 flush。
+	evs, err := ReadSessionLog(dir, sid)
+	if err != nil {
+		t.Fatalf("读回会话日志失败：%v", err)
+	}
+	if len(evs) == 0 {
+		t.Fatal("会话日志是空的 —— 用户提问没落盘")
+	}
+
+	// ① 首条必须是 user，且文本原样。
+	if evs[0].Kind != "user" {
+		t.Fatalf("首条期望 kind=user（用户提问应先于引擎事件落盘），实得 %q；全部：%s", evs[0].Kind, dumpKinds(evs))
+	}
+	if evs[0].Text != prompt {
+		t.Fatalf("首条 user 文本被改动：\n期望 %q\n实得 %q", prompt, evs[0].Text)
+	}
+	if evs[0].SessionID != sid {
+		t.Fatalf("首条应带上 session_id（pending 刷盘时回填），实得 %q", evs[0].SessionID)
+	}
+
+	// ② 引擎事件也都在，且排在 user 之后。
+	sawText := false
+	for i := 1; i < len(evs); i++ {
+		if evs[i].Kind == "text" && evs[i].Text == "收到" {
+			sawText = true
+		}
+	}
+	if !sawText {
+		t.Fatalf("引擎的 text 事件没落盘；全部：%s", dumpKinds(evs))
+	}
+
+	// ③ seq 从 1 起、严格递增（历史接口靠它做游标）。
+	for i, ev := range evs {
+		if ev.Seq != uint64(i+1) {
+			t.Fatalf("第 %d 条 seq 期望 %d，实得 %d（seq 必须从 1 起连续递增）", i, i+1, ev.Seq)
+		}
+	}
+
+	// ④ 落盘文件与 CLI 的 schema 一致：kind 字段（不是 type），这也是移动端渲染器
+	//    必须两套都认的原因。
+	raw := readLines(t, filepath.Join(dir, sid+".jsonl"))
+	if len(raw) == 0 {
+		t.Fatal("落盘文件是空的")
+	}
+	var first map[string]any
+	if err := json.Unmarshal([]byte(raw[0]), &first); err != nil {
+		t.Fatal(err)
+	}
+	if first["kind"] != "user" {
+		t.Fatalf("落盘首行的字段应是 kind=user，实得 %v", first)
+	}
+	if _, hasType := first["type"]; hasType {
+		t.Fatal("落盘格式用的是 kind，不该出现 type 字段")
+	}
+}
+
+func dumpKinds(evs []sessionEvent) string {
+	out := ""
+	for i, ev := range evs {
+		if i > 0 {
+			out += ", "
+		}
+		out += ev.Kind
+	}
+	return "[" + out + "]"
+}

package/internal/cli/toolkind_wire_test.go

@@ -0,0 +1,84 @@
+package cli
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+/* 工具子形态上 wire 的证据（2026-09-29）。
+ *
+ * 为什么值得单独钉一条：这个字段是**两个界面**（旧工作台 / PC 基础对话 UI）选卡的唯一依据，
+ * 而它只在 tool_use 事件上出现。没有这条断言，某天有人在 payload 里漏带它，
+ * 表现是「工具卡悄悄退回按名字猜」—— 界面上不报错，只是慢慢和新引擎对不上。 */
+func TestStreamPayloadCarriesToolKind(t *testing.T) {
+	// ① 工具调用：带上判定结果
+	p := streamEventPayload(agent.StreamEvent{Kind: agent.KindToolUse, Name: "Bash", Text: `{"cmd":"ls"}`})
+	b, err := json.Marshal(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatal(err)
+	}
+	if got["tool_kind"] != agent.ToolKindCommand {
+		t.Errorf("tool_use 的 tool_kind = %v, want %q（payload: %s）", got["tool_kind"], agent.ToolKindCommand, b)
+	}
+
+	// ② MCP 的名字带命名空间前缀，仍然要判成 mcp
+	b2, _ := json.Marshal(streamEventPayload(agent.StreamEvent{Kind: agent.KindToolUse, Name: "mcp__github__create_issue"}))
+	var got2 map[string]any
+	_ = json.Unmarshal(b2, &got2)
+	if got2["tool_kind"] != agent.ToolKindMCP {
+		t.Errorf("mcp 工具的 tool_kind = %v, want %q", got2["tool_kind"], agent.ToolKindMCP)
+	}
+
+	// ③ 工具**结果**不带：它的 Name 放的是关联的 tool_use.id，拿来判形态会把 id 当工具名
+	b3, _ := json.Marshal(streamEventPayload(agent.StreamEvent{Kind: agent.KindToolResult, Name: "toolu_01abc", Text: "ok"}))
+	var got3 map[string]any
+	_ = json.Unmarshal(b3, &got3)
+	if _, has := got3["tool_kind"]; has {
+		t.Errorf("tool_result 不该带 tool_kind：%s", b3)
+	}
+
+	// ④ 非工具事件：字段整个省掉（老消费者的字段集不受影响）
+	b4, _ := json.Marshal(streamEventPayload(agent.StreamEvent{Kind: agent.KindText, Text: "你好"}))
+	var got4 map[string]any
+	_ = json.Unmarshal(b4, &got4)
+	if _, has := got4["tool_kind"]; has {
+		t.Errorf("text 事件不该带 tool_kind：%s", b4)
+	}
+}
+
+/* 会话日志与 SSE 用**同一个**判定：两边画出的卡才会是同一张。
+ * 这里钉住日志事件的字段（history 回放走的就是它）。 */
+func TestSessionEventCarriesToolKind(t *testing.T) {
+	ev := agent.StreamEvent{Kind: agent.KindToolUse, Name: "Edit", Text: `{"file":"a.go"}`}
+	se := sessionEvent{
+		Kind: string(ev.Kind), Text: ev.Text, Name: ev.Name, ID: ev.ID,
+		ToolKind: toolKindOfEvent(ev),
+	}
+	if se.ToolKind != agent.ToolKindFileChange {
+		t.Errorf("日志里的 tool_kind = %q, want %q", se.ToolKind, agent.ToolKindFileChange)
+	}
+	b, err := json.Marshal(se)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]any
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatal(err)
+	}
+	if got["tool_kind"] != agent.ToolKindFileChange {
+		t.Errorf("日志事件的 tool_kind = %v, want %q（%s）", got["tool_kind"], agent.ToolKindFileChange, b)
+	}
+	// 非工具事件不带这个键（omitempty）
+	b2, _ := json.Marshal(sessionEvent{Kind: "text", Text: "hi"})
+	var got2 map[string]any
+	_ = json.Unmarshal(b2, &got2)
+	if _, has := got2["tool_kind"]; has {
+		t.Errorf("text 日志事件不该带 tool_kind：%s", b2)
+	}
+}

package/internal/cli/workspace_test.go

@@ -0,0 +1,188 @@
+package cli
+
+// workspace_test.go - `-w/--workspace` 的 CLI 侧单测。
+//
+// 覆盖：
+//  ① 值解析：展开 ~、转绝对路径、必须存在且是目录（不存在/是文件 → 参数错误 exit 2 语义）
+//  ② 透传：进入 Request.Workspace（假引擎回收）
+//  ③ 不支持要说明白：llm / arkclaw 给出 stderr 提示文案，其余引擎不提示
+//  ④ --engines 每行带 workspace 能力字段（机器可读）
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// wsCaptureEngine 记录收到的 Request.Workspace。
+type wsCaptureEngine struct {
+	name string
+	got  string
+}
+
+func (e *wsCaptureEngine) Name() string           { return e.name }
+func (e *wsCaptureEngine) Detect() (bool, string) { return true, "fake://" + e.name }
+func (e *wsCaptureEngine) Complete(_ context.Context, req agent.Request) (agent.Response, error) {
+	e.got = req.Workspace
+	return agent.Response{Text: "ok", Model: req.Model}, nil
+}
+
+func TestWorkspaceFlagPassedToEngine(t *testing.T) {
+	ws := t.TempDir()
+	e := &wsCaptureEngine{name: "ws-echo"}
+	registerFake(e)
+
+	stdout, stderr, err := runAskCmd(t, "", "-e", "ws-echo", "-w", ws, "-o", "text", "hi")
+	if err != nil {
+		t.Fatalf("ask: %v (stderr=%s)", err, stderr)
+	}
+	if !strings.Contains(stdout, "ok") {
+		t.Errorf("stdout = %q", stdout)
+	}
+	// 路径会转绝对 + 规整（t.TempDir 在 macOS 上是 /var → /private/var 的软链）
+	want, _ := filepath.EvalSymlinks(ws)
+	got, _ := filepath.EvalSymlinks(e.got)
+	if got != want {
+		t.Errorf("Request.Workspace = %q, want %q", got, want)
+	}
+	// 支持的引擎不该有「不支持」提示
+	if strings.Contains(stderr, "不支持指定工作目录") {
+		t.Errorf("ws-echo 不该被提示不支持：%s", stderr)
+	}
+}
+
+func TestWorkspaceFlagExpandsTilde(t *testing.T) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skip("no home dir")
+	}
+	if _, err := resolveWorkspaceDir("~"); err != nil {
+		t.Fatalf(`resolveWorkspaceDir("~") = %v`, err)
+	}
+	got, err := resolveWorkspaceDir("~")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want, _ := filepath.EvalSymlinks(home); func() bool { g, _ := filepath.EvalSymlinks(got); return g != want }() {
+		t.Errorf(`resolveWorkspaceDir("~") = %q, want %q`, got, home)
+	}
+}
+
+func TestWorkspaceFlagRejectsBadPath(t *testing.T) {
+	registerFake(&wsCaptureEngine{name: "ws-echo-bad"})
+
+	// 不存在
+	_, _, err := runAskCmd(t, "", "-e", "ws-echo-bad", "-w", filepath.Join(t.TempDir(), "nope"), "hi")
+	if err == nil || !strings.Contains(err.Error(), "--workspace") {
+		t.Errorf("不存在的目录应报参数错误并点明 --workspace，实得 %v", err)
+	}
+
+	// 是文件不是目录
+	f := filepath.Join(t.TempDir(), "afile")
+	if werr := os.WriteFile(f, []byte("x"), 0o644); werr != nil {
+		t.Fatal(werr)
+	}
+	_, _, err = runAskCmd(t, "", "-e", "ws-echo-bad", "-w", f, "hi")
+	if err == nil || !strings.Contains(err.Error(), "不是目录") {
+		t.Errorf("指向文件应报「不是目录」，实得 %v", err)
+	}
+}
+
+func TestWorkspaceUnsupportedWarnText(t *testing.T) {
+	for _, engine := range []string{"llm", "arkclaw", "openclaw"} {
+		warn := workspaceUnsupportedWarn(engine)
+		if !strings.Contains(warn, engine) || !strings.Contains(warn, "-w/--workspace 已忽略") {
+			t.Errorf("workspaceUnsupportedWarn(%q) = %q，应说明被忽略", engine, warn)
+		}
+	}
+	for _, engine := range []string{"claude", "codebuddy", "codebuddy-ai", "trae", "codex"} {
+		if warn := workspaceUnsupportedWarn(engine); warn != "" {
+			t.Errorf("workspaceUnsupportedWarn(%q) = %q，支持 workspace 的引擎不该提示", engine, warn)
+		}
+	}
+}
+
+func TestEnginesFlagCarriesWorkspaceCapability(t *testing.T) {
+	// ⚠️ 测试进程里的引擎注册表是**假的**：agent.Engines() 只在 registry 为空时才
+	// initEngines()，而本包测试先 Register 了假引擎 → 真实引擎不会出现。故这里按名字
+	// 注册几个具有代表性的假引擎（codex=flag:-C / llm=arkclaw=none / claude=cwd）。
+	registerFake(&wsCaptureEngine{name: "codex"})
+	registerFake(&wsCaptureEngine{name: "llm"})
+	registerFake(&wsCaptureEngine{name: "arkclaw"})
+	registerFake(&wsCaptureEngine{name: "claude"})
+	registerFake(&wsCaptureEngine{name: "dsh"})
+	registerFake(&wsCaptureEngine{name: "ws-cap-unlisted"})
+
+	stdout, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	var rows []struct {
+		Engine    string `json:"engine"`
+		Workspace string `json:"workspace"`
+		Streaming bool   `json:"streaming"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(stdout)), &rows); err != nil {
+		t.Fatalf("解析 --engines 输出失败: %v (%s)", err, stdout)
+	}
+	got := map[string]string{}
+	for _, r := range rows {
+		got[r.Engine] = r.Workspace
+	}
+	for engine, want := range map[string]string{
+		"codex":           "flag:-C",
+		"llm":             "none",
+		"arkclaw":         "none",
+		"claude":          "cwd",
+		"dsh":             "cwd", // 调用目录即 workspace 根（子进程 cwd）
+		"ws-cap-unlisted": "cwd", // 未识别的引擎按默认（子进程 cwd）处理
+	} {
+		if got[engine] != want {
+			t.Errorf("--engines 里 %s 的 workspace = %q, want %q", engine, got[engine], want)
+		}
+	}
+	// streaming：假引擎只实现 Complete → 一律 false；真实 codex 引擎实现了 Stream → true
+	streaming := map[string]bool{}
+	for _, r := range rows {
+		streaming[r.Engine] = r.Streaming
+	}
+	if streaming["ws-cap-unlisted"] {
+		t.Error("只实现 Complete 的假引擎 streaming 应为 false")
+	}
+	registerFake(&fakeStreamEngine{name: "stream-cap"})
+	stdout2, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines(2): %v", err)
+	}
+	var rows2 []struct {
+		Engine    string `json:"engine"`
+		Streaming bool   `json:"streaming"`
+	}
+	if err := json.Unmarshal([]byte(strings.TrimSpace(stdout2)), &rows2); err != nil {
+		t.Fatalf("解析失败: %v", err)
+	}
+	for _, r := range rows2 {
+		if r.Engine == "stream-cap" && !r.Streaming {
+			t.Error("实现了 Streamer 的引擎 streaming 应为 true")
+		}
+	}
+}
+
+// fakeStreamEngine 同时实现 Engine + Streamer（用于 streaming 能力字段断言）。
+type fakeStreamEngine struct {
+	name string
+}
+
+func (e *fakeStreamEngine) Name() string           { return e.name }
+func (e *fakeStreamEngine) Detect() (bool, string) { return true, "fake://" + e.name }
+func (e *fakeStreamEngine) Complete(_ context.Context, _ agent.Request) (agent.Response, error) {
+	return agent.Response{Text: "ok"}, nil
+}
+func (e *fakeStreamEngine) Stream(_ context.Context, _ agent.Request, _ func(agent.StreamEvent)) (agent.StreamResult, error) {
+	return agent.StreamResult{Response: agent.Response{Text: "ok"}}, nil
+}