magic-agent 1.0.0

package/internal/cli/attach_test.go

@@ -0,0 +1,239 @@
+package cli
+
+// attach_test.go - 「文件＋提示词」（-a/--attach 附件）的 CLI 层测试。
+//
+// 用户需求原文（2026-09-17）：「理解不对 是文件＋提示词 比如截图加提示词」。
+//
+// 覆盖：-a 的路径解析与校验（缺失 / 目录 / 逗号 / 去重 / ~ 展开）、附件透传到 Request、
+// 无原生附件通道的引擎（trae / openclaw）降级为「路径写进提示词」时的 stderr 提示、
+// 以及 `--engines` 的 attachments 能力字段。
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeAttachFile 写一个测试文件（内容随意 —— MIME 由魔数/扩展名嗅探，这里只关心路径链路）。
+func writeAttachFile(t *testing.T, name, content string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), name)
+	if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+// ── resolveAttachments ───────────────────────────────────────
+
+func TestResolveAttachmentsSplitsAndDedupes(t *testing.T) {
+	a := writeAttachFile(t, "a.png", "\x89PNG\r\n\x1a\n")
+	b := writeAttachFile(t, "b.md", "hi")
+
+	got, err := resolveAttachments([]string{a + "," + b, a}) // 逗号 + 重复
+	if err != nil {
+		t.Fatalf("resolveAttachments: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("附件数 = %d want 2（去重后）: %+v", len(got), got)
+	}
+	if got[0].Path != a || got[1].Path != b {
+		t.Errorf("路径应转绝对且保持顺序: %+v", got)
+	}
+	if got[0].MIME != "image/png" {
+		t.Errorf("a.png 的 MIME = %q want image/png（魔数）", got[0].MIME)
+	}
+	if got[1].MIME != "text/plain" {
+		t.Errorf("b.md 的 MIME = %q want text/plain", got[1].MIME)
+	}
+}
+
+func TestResolveAttachmentsErrors(t *testing.T) {
+	if _, err := resolveAttachments([]string{"/no/such/shot.png"}); err == nil {
+		t.Error("不存在的附件应报错")
+	}
+	if _, err := resolveAttachments([]string{t.TempDir()}); err == nil {
+		t.Error("目录应报错（不是普通文件）")
+	}
+	// 全空白 → 视作没有附件（不报错）
+	got, err := resolveAttachments([]string{"  ", ","})
+	if err != nil || len(got) != 0 {
+		t.Errorf("空白输入应得到 0 个附件: %+v err=%v", got, err)
+	}
+}
+
+// ── -a/--attach 透传 ─────────────────────────────────────────
+
+// 有原生附件通道的引擎（claude）：附件进 Request，且不打降级警告。
+func TestAttachFlagReachesRequest(t *testing.T) {
+	capEng := &capturingEngine{name: "claude"}
+	registerFake(capEng)
+	img := writeAttachFile(t, "shot.png", "\x89PNG\r\n\x1a\n")
+
+	_, stderr, err := runAskCmd(t, "", "-e", "claude", "-p", "这张图什么颜色", "-a", img)
+	if err != nil {
+		t.Fatalf("ask: %v", err)
+	}
+	if len(capEng.lastAttach) != 1 {
+		t.Fatalf("附件数 = %d want 1", len(capEng.lastAttach))
+	}
+	if capEng.lastAttach[0].Path != img {
+		t.Errorf("附件路径 = %q want %q", capEng.lastAttach[0].Path, img)
+	}
+	if capEng.lastAttach[0].MIME != "image/png" {
+		t.Errorf("附件 MIME = %q", capEng.lastAttach[0].MIME)
+	}
+	if strings.Contains(stderr, "没有附件输入通道") {
+		t.Errorf("claude 有原生通道，不该打降级警告: %q", stderr)
+	}
+	// 提示词本身不受影响
+	if capEng.lastPrompt != "这张图什么颜色" {
+		t.Errorf("prompt = %q", capEng.lastPrompt)
+	}
+}
+
+// 多个 -a 与逗号分隔等价。
+func TestAttachFlagMultiple(t *testing.T) {
+	// 注意：不能用 "claude" 这个名字 —— 上一个用例已注册同名假引擎，
+	// Lookup 取注册表里首个匹配 → 断言会打到别的实例上（我第一版就这么挂的）。
+	capEng := &capturingEngine{name: "fake-attmulti"}
+	registerFake(capEng)
+	a := writeAttachFile(t, "1.png", "\x89PNG\r\n\x1a\n")
+	b := writeAttachFile(t, "2.png", "\x89PNG\r\n\x1a\n")
+	c := writeAttachFile(t, "3.png", "\x89PNG\r\n\x1a\n")
+
+	// -a 可重复，也接受逗号分隔
+	_, _, err := runAskCmd(t, "", "-e", "fake-attmulti", "-p", "看图", "-a", a, "-a", b+","+c)
+	if err != nil {
+		t.Fatalf("ask: %v", err)
+	}
+	if len(capEng.lastAttach) != 3 {
+		t.Errorf("附件数 = %d want 3（-a 重复 + 逗号分隔）", len(capEng.lastAttach))
+	}
+}
+
+// 附件路径错误 → usage error（exit 2），不静默忽略。
+func TestAttachFlagBadPathIsUsageError(t *testing.T) {
+	registerFake(&stringEngine{name: "fake-attbad", text: "x"})
+
+	_, _, err := runAskCmd(t, "", "-e", "fake-attbad", "-p", "hi", "-a", "/no/such/shot.png")
+	if err == nil {
+		t.Fatal("应报错")
+	}
+	if _, ok := err.(*usageError); !ok {
+		t.Errorf("应是 usageError(exit 2), got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "--attach") {
+		t.Errorf("错误信息应点明 --attach: %v", err)
+	}
+}
+
+// ── 无原生通道引擎的降级提示 ─────────────────────────────────
+
+func TestAttachmentPromptFallbackWarnUnit(t *testing.T) {
+	// 有原生通道 → 无提示
+	for _, e := range []string{"claude", "codebuddy", "codebuddy-ai", "codex", "llm", "arkclaw"} {
+		if got := attachmentPromptFallbackWarn(e, 1, true); got != "" {
+			t.Errorf("%s 有原生通道，不该提示: %q", e, got)
+		}
+	}
+	// 无附件 → 无提示
+	if got := attachmentPromptFallbackWarn("trae", 0, true); got != "" {
+		t.Errorf("无附件不该提示: %q", got)
+	}
+	// trae + 工具开 → 提示但不提 --tools
+	got := attachmentPromptFallbackWarn("trae", 2, false)
+	if !strings.Contains(got, "trae") || !strings.Contains(got, "2 个附件") || strings.Contains(got, "--tools off") {
+		t.Errorf("trae/工具开 的提示不对: %q", got)
+	}
+	// trae + 工具关 → 必须点明读不到
+	gotOff := attachmentPromptFallbackWarn("trae", 1, true)
+	if !strings.Contains(gotOff, "--tools off") || !strings.Contains(gotOff, "--tools on") {
+		t.Errorf("工具关时必须点明：%q", gotOff)
+	}
+	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)
+		}
+	}
+}
+
+// 端到端：trae（无原生通道）带附件 + 默认 --tools off → stderr 出现降级提示。
+func TestAttachFlagWarnsOnPromptFallbackEngine(t *testing.T) {
+	registerFake(&stringEngine{name: "trae", text: "ok"})
+	img := writeAttachFile(t, "shot.png", "\x89PNG\r\n\x1a\n")
+
+	_, 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)
+	}
+
+	// --tools on → 只提示降级，不再提读不到
+	_, stderrOn, err := runAskCmd(t, "", "-e", "trae", "-p", "看图", "--tools", "on", "-a", img)
+	if err != nil {
+		t.Fatalf("ask: %v", err)
+	}
+	if !strings.Contains(stderrOn, "没有附件输入通道") {
+		t.Errorf("仍应提示降级, got %q", stderrOn)
+	}
+	if strings.Contains(stderrOn, "--tools off") {
+		t.Errorf("工具已开，不该再提 --tools off: %q", stderrOn)
+	}
+}
+
+// ── --engines 的 attachments 字段 ────────────────────────────
+
+func TestEnginesFlagCarriesAttachmentsCapability(t *testing.T) {
+	registerFake(&stringEngine{name: "codex"})
+	registerFake(&stringEngine{name: "claude"})
+	registerFake(&stringEngine{name: "arkclaw"})
+	registerFake(&stringEngine{name: "trae"})
+	registerFake(&stringEngine{name: "dsh"})
+
+	stdout, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	var rows []struct {
+		Engine      string `json:"engine"`
+		Attachments string `json:"attachments"`
+	}
+	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.Attachments
+	}
+	for engine, want := range map[string]string{
+		"codex":   "flag:-i",
+		"claude":  "stdin:stream-json",
+		"arkclaw": "part:file",
+		"trae":    "prompt",
+		"dsh":     "prompt", // headless 无附件参数 → 路径写进提示词
+	} {
+		if got[engine] != want {
+			t.Errorf("--engines 里 %s 的 attachments = %q want %q", engine, got[engine], want)
+		}
+	}
+	// 每条都必须有该字段（omitempty 也不能漏 —— 调用方据此决定要不要发附件）
+	for _, r := range rows {
+		if r.Attachments == "" {
+			t.Errorf("%s 缺 attachments 字段", r.Engine)
+		}
+	}
+}

package/internal/cli/contract_test.go

@@ -0,0 +1,157 @@
+package cli
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/darren/magic-agent/internal/agent"
+)
+
+// contractRow 是 --engines / --contract 每一行里本测试关心的字段。
+type contractRow struct {
+	Engine       string   `json:"engine"`
+	OK           bool     `json:"ok"`
+	Capabilities []string `json:"capabilities"`
+	Models       []string `json:"models"`
+}
+
+// TestContractEnvelope -- `--contract` 的顶层形状与契约版本。
+//
+// 客户端启动时靠这两个东西做校验：contractVersion 决定"我能不能解析这份输出"，
+// capabilities 决定"界面画成什么样"。
+func TestContractEnvelope(t *testing.T) {
+	stdout, _, err := runAskCmd(t, "", "--contract")
+	if err != nil {
+		t.Fatalf("--contract: %v", err)
+	}
+	var env struct {
+		ContractVersion int           `json:"contractVersion"`
+		Features        []string      `json:"features"`
+		Engines         []contractRow `json:"engines"`
+	}
+	if err := json.Unmarshal([]byte(stdout), &env); err != nil {
+		t.Fatalf("解析 --contract 输出失败: %v（原始输出：%s）", err, stdout)
+	}
+	if env.ContractVersion != agent.ContractVersion {
+		t.Errorf("contractVersion = %d want %d", env.ContractVersion, agent.ContractVersion)
+	}
+	// 核心级通道能力：客户端据此判断这台 core 支不支持 --events / --control。
+	for _, want := range []string{agent.FeatureSessionEvents, agent.FeatureSessionControl} {
+		found := false
+		for _, f := range env.Features {
+			if f == want {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("features 缺 %s，实际 %v", want, env.Features)
+		}
+	}
+	if got, want := len(env.Engines), len(agent.Engines()); got != want {
+		t.Errorf("engines 行数 = %d want %d", got, want)
+	}
+	for _, row := range env.Engines {
+		if row.Engine == "" {
+			t.Errorf("有一行缺 engine 字段：%+v", row)
+		}
+		if len(row.Capabilities) == 0 {
+			t.Errorf("%s: capabilities 为空（客户端会画不出这个引擎）", row.Engine)
+		}
+		/* ⚠️ --contract 默认不探测模型：每个引擎的模型探测都要起一次真 CLI 进程
+		   （10 个引擎约 30s 级），客户端在启动路径上等不起。有人把默认改回探测时
+		   这条会红，正好提醒他去看 runContract 的注释。 */
+		if len(row.Models) != 0 {
+			t.Errorf("%s: --contract 默认不应探测模型，却给出了 models=%v", row.Engine, row.Models)
+		}
+	}
+}
+
+// TestEnginesTopLevelStaysArray -- `--engines` 顶层必须仍是数组。
+//
+// 老调用方（含 magic-test 的 engines.cjs）按数组解析；契约信息走 --contract 的
+// envelope，不能把老入口改成对象 —— 那是静默破坏。
+func TestEnginesTopLevelStaysArray(t *testing.T) {
+	stdout, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	trimmed := strings.TrimSpace(stdout)
+	if !strings.HasPrefix(trimmed, "[") {
+		t.Fatalf("--engines 顶层必须是 JSON 数组（老调用方按数组解析），实际开头是 %q", firstRunes(trimmed, 32))
+	}
+}
+
+// TestEnginesCarriesCapabilities -- 老入口也要带 capabilities（纯加字段，向后兼容）。
+func TestEnginesCarriesCapabilities(t *testing.T) {
+	stdout, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+	var rows []contractRow
+	if err := json.Unmarshal([]byte(stdout), &rows); err != nil {
+		t.Fatalf("解析 --engines 输出失败: %v（原始输出：%s）", err, stdout)
+	}
+	if len(rows) == 0 {
+		t.Fatal("--engines 没有任何一行")
+	}
+	for _, row := range rows {
+		if len(row.Capabilities) == 0 {
+			t.Errorf("%s: --engines 每行都应带 capabilities，实际为空", row.Engine)
+		}
+	}
+}
+
+// TestContractAndEnginesRowsAgree -- 两个入口的行必须由同一份构建逻辑产出：
+// 同名引擎的 **capabilities**（静态声明）应逐项一致。
+//
+// ⚠️ 刻意**不比对 ok / streaming / models**：它们是运行态，两次独立进程的探测结果
+// 可以合法地不同（arkclaw 这类远端网关的 ok 取决于可达性与配置）。这也正是把
+// capabilities 与运行态分开的原因 —— 静态的那部分必须稳定，动态的那部分本就会变。
+func TestContractAndEnginesRowsAgree(t *testing.T) {
+	contractOut, _, err := runAskCmd(t, "", "--contract")
+	if err != nil {
+		t.Fatalf("--contract: %v", err)
+	}
+	enginesOut, _, err := runAskCmd(t, "", "--engines", "--no-models")
+	if err != nil {
+		t.Fatalf("--engines: %v", err)
+	}
+
+	var env struct {
+		Engines []contractRow `json:"engines"`
+	}
+	var rows []contractRow
+	if err := json.Unmarshal([]byte(contractOut), &env); err != nil {
+		t.Fatalf("解析 --contract 失败: %v", err)
+	}
+	if err := json.Unmarshal([]byte(enginesOut), &rows); err != nil {
+		t.Fatalf("解析 --engines 失败: %v", err)
+	}
+
+	byName := map[string]contractRow{}
+	for _, r := range rows {
+		byName[r.Engine] = r
+	}
+	for _, c := range env.Engines {
+		e, ok := byName[c.Engine]
+		if !ok {
+			t.Errorf("--contract 里的 %s 在 --engines 里没有", c.Engine)
+			continue
+		}
+		if strings.Join(e.Capabilities, ",") != strings.Join(c.Capabilities, ",") {
+			t.Errorf("%s: capabilities 不一致（--engines=%v / --contract=%v）",
+				c.Engine, e.Capabilities, c.Capabilities)
+		}
+	}
+}
+
+// firstRunes 取前 n 个字符用于报错信息（避免把整段 JSON 打进日志）。
+func firstRunes(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return s
+	}
+	return string(r[:n]) + "…"
+}

package/internal/cli/control.go

@@ -0,0 +1,149 @@
+package cli
+
+import (
+	"bufio"
+	"encoding/json"
+	"io"
+	"strings"
+	"sync"
+	"sync/atomic"
+)
+
+/* stdin 控制通道（--control）：给流式会话一条**回传**通道。
+ *
+ * 为什么需要（2026-09-27）：`--stream` 此前是单向的 —— 调用方只能看，不能打断长任务、
+ * 也不能回审批。而桌面 / 移动端最核心的两个动作恰好就是这两件（手机负责控制、
+ * 工作设备负责执行）。
+ *
+ * 协议：stdin 一行一条 NDJSON 命令（与 stdout 的事件流同构，便于同一套解析器处理）。
+ * 应答只在 `--events` 形态下输出（老形状不注入新事件类型）：
+ *
+ *   {"op":"ping"}                       → {"type":"pong"}
+ *   {"op":"interrupt","reason":"..."}   → 打断当前轮；**等这一轮真的结束**再发
+ *                                         {"type":"interrupted","reason":"..."}
+ *   {"op":"stop"}                       → 收工（关闭常驻会话的追加入口）→ {"type":"stopped"}
+ *   {"op":"answer","text":"..."}        → 把答案作为后续 user 消息追进常驻会话
+ *                                         → {"type":"answered"}；通道不可用 →
+ *                                           {"type":"control_error","error":"..."}
+ *   其它                                 → {"type":"control_error","op":"..."}
+ *
+ * ⚠️ answer 为什么走「后续 user 消息」而不是原地作答：headless 下 claude 在模型提问后
+ * 会**立刻自行拒绝**（见 agent.KindAsk 的注释），唯一能把答案真正喂给模型的通道就是
+ * 下一轮 user 消息 —— 也就是常驻会话的追加通道，与 `--append` 是同一条路。
+ * 因此 answer 只在常驻会话生效时可用；不可用时明确回一条 control_error，不静默丢弃。
+ */
+
+// controlCommand 一条控制命令。
+type controlCommand struct {
+	Op     string `json:"op"`
+	Reason string `json:"reason,omitempty"`
+	Text   string `json:"text,omitempty"`
+}
+
+// controlHooks 控制命令的落地动作。
+type controlHooks struct {
+	// interrupt 打断当前轮（取消 ctx → 引擎进程组随之被收拾）。
+	interrupt func(reason string)
+	// stop 收工：关掉常驻会话的追加入口，让引擎正常收尾。
+	stop func()
+	// answer 把答案追进常驻会话；返回 false 表示通道此刻不可用。
+	answer func(text string) bool
+}
+
+// controlSession 一次控制通道的生命周期。
+type controlSession struct {
+	sink    *eventSink
+	hooks   controlHooks
+	stopFlg atomic.Bool
+	intrFlg atomic.Bool
+	closed  chan struct{}
+	once    sync.Once
+}
+
+// startControlReader 起一个后台 goroutine 读 NDJSON 命令。调用方负责 Close。
+func startControlReader(r io.Reader, sink *eventSink, hooks controlHooks) *controlSession {
+	s := &controlSession{sink: sink, hooks: hooks, closed: make(chan struct{})}
+	go s.loop(r)
+	return s
+}
+
+func (s *controlSession) loop(r io.Reader) {
+	sc := bufio.NewScanner(r)
+	// 单条命令上限 4MiB：answer 可能带一段很长的说明（截图说明、报错粘贴）。
+	sc.Buffer(make([]byte, 0, 64*1024), 4*1024*1024)
+	for sc.Scan() {
+		select {
+		case <-s.closed:
+			return
+		default:
+		}
+		line := strings.TrimSpace(sc.Text())
+		if line == "" {
+			continue
+		}
+		var c controlCommand
+		if err := json.Unmarshal([]byte(line), &c); err != nil {
+			_ = s.sink.notice("control_error", map[string]any{"error": "不是合法 NDJSON 命令：" + err.Error()})
+			continue
+		}
+		s.dispatch(c)
+	}
+}
+
+// dispatch 执行一条命令。未知 op 只回一条 control_error，**不中断读取** ——
+// 一个拼错的 op 不该让整条控制通道失效。
+func (s *controlSession) dispatch(c controlCommand) {
+	switch strings.ToLower(strings.TrimSpace(c.Op)) {
+	case "ping":
+		_ = s.sink.notice("pong", nil)
+
+	case "interrupt":
+		// 不在这里回应答：interrupt 的真实含义是「这一轮真的结束了」，
+		// 由 runStreamAsk 在 Stream 返回后发 interrupted。
+		s.intrFlg.Store(true)
+		if s.hooks.interrupt != nil {
+			s.hooks.interrupt(c.Reason)
+		}
+
+	case "stop":
+		s.stopFlg.Store(true)
+		if s.hooks.stop != nil {
+			s.hooks.stop()
+		}
+		_ = s.sink.notice("stopped", nil)
+
+	case "answer":
+		text := strings.TrimSpace(c.Text)
+		if text == "" {
+			_ = s.sink.notice("control_error", map[string]any{"op": "answer", "error": "answer 需要 text 字段"})
+			return
+		}
+		if s.hooks.answer == nil || !s.hooks.answer(text) {
+			_ = s.sink.notice("control_error", map[string]any{
+				"op": "answer",
+				"error": "常驻会话未生效，answer 无处可去。" +
+					"答案要走常驻会话的追加通道（headless 下模型拿不到原地作答）；" +
+					"请确认引擎支持 append（见 --contract 的 capabilities）且 --keep-alive 生效",
+			})
+			return
+		}
+		_ = s.sink.notice("answered", nil)
+
+	default:
+		_ = s.sink.notice("control_error", map[string]any{
+			"op":    c.Op,
+			"error": "未知 op：支持 ping / interrupt / stop / answer",
+		})
+	}
+}
+
+// WasStopped 收到过 stop。
+func (s *controlSession) WasStopped() bool { return s.stopFlg.Load() }
+
+// WasInterrupted 收到过 interrupt（应答由调用方在本轮结束时发出）。
+func (s *controlSession) WasInterrupted() bool { return s.intrFlg.Load() }
+
+// Close 停止读取（幂等）。已经在阻塞读 stdin 的 goroutine 会在下一次 Scan 返回后退出。
+func (s *controlSession) Close() {
+	s.once.Do(func() { close(s.closed) })
+}