magic-agent 1.0.0

package/internal/agent/capability.go

@@ -0,0 +1,154 @@
+package agent
+
+import "sort"
+
+/* 契约版本与能力标识 —— magic-client（桌面 / 移动客户端插件）契约面 v1。
+ *
+ * 为什么需要（2026-09-27）：客户端只能通过「唯一来源」拿到引擎能力，否则每个
+ * 接入方都会自己写一遍 switch，最后各自漂移。实测已经踩过的同类事故：
+ * 客户端拿不到能力字段 → 界面空白；桌面上层按版本号挑二进制 → 挑到旧构建。
+ *
+ * 与既有 `*SupportOf` 表的关系：那些表给的是「落地方式」（flag:-i /
+ * stdin:stream-json / part:file / prompt / none…），属于实现细节；能力 id 是
+ * 「结论」（这个引擎能不能收附件、能不能续接）。两者由同一批表推导，实现
+ * 细节变化时能力 id 不必跟着变 —— 客户端只认结论。
+ *
+ * 静态与运行态的边界（重要）：
+ *   capabilities  静态声明，回答「能做什么」，不启动任何 CLI 就能算出来；
+ *   ok / streaming / models / version  运行态，回答「此刻如何」，探测才拿得到。
+ * 客户端按 capabilities 决定界面形态，按运行态决定按钮可用性与降级提示。
+ */
+
+// ContractVersion 契约面版本。客户端拿它与自己的期望范围比对，超出范围应**明确
+// 报错**并提示升级，而不是带着不匹配的能力继续跑。
+//
+// 递增规则：只增字段（向后兼容）不升版本；一旦有字段改名、语义变化或删除，
+// 必须升版本 —— 老客户端会因版本不匹配而拒绝启动，这正是我们想要的结果。
+const ContractVersion = 1
+
+// 能力 id。命名规则：`域.能力`，域只有 session / workspace / attachment /
+// model / engine 五个，客户端按域分组渲染即可。
+const (
+	// CapSessionStream 支持 `--stream`：正文或思考增量实时到达（成色见各引擎注释）。
+	CapSessionStream = "session.stream"
+	// CapSessionAppend 支持常驻会话 + `--append` 追加消息。
+	CapSessionAppend = "session.append"
+	// CapSessionAsk 支持「需要用户选择」的往返（`{"type":"ask"}` 事件）。
+	CapSessionAsk = "session.ask"
+	// CapSessionPermission 支持四档权限模型（manual / accept-edits / auto / full）。
+	CapSessionPermission = "session.permission"
+	// CapWorkspaceSelect 能指定工作目录（原生 flag 或子进程 cwd）。
+	CapWorkspaceSelect = "workspace.select"
+	// CapAttachmentNative 附件走引擎的原生通道（图片真的进模型上下文）。
+	CapAttachmentNative = "attachment.native"
+	// CapAttachmentPrompt 附件只有降级通道：把绝对路径写进提示词，靠引擎自己读文件。
+	CapAttachmentPrompt = "attachment.prompt"
+	// CapModelList 有动态模型清单来源（`--engines` 的 models 字段）。
+	CapModelList = "model.list"
+	// CapModelCredits 能给出各模型的积分倍率（`model_credits` 字段）。
+	CapModelCredits = "model.credits"
+	// CapEngineInstall 有一键安装 / 升级命令（`install` 字段）。
+	CapEngineInstall = "engine.install"
+)
+
+// CapabilityIDs 返回全部已知能力 id（字典序，稳定）。用于校验与文档生成。
+func CapabilityIDs() []string {
+	out := []string{
+		CapAttachmentNative,
+		CapAttachmentPrompt,
+		CapEngineInstall,
+		CapModelCredits,
+		CapModelList,
+		CapSessionAppend,
+		CapSessionAsk,
+		CapSessionPermission,
+		CapSessionStream,
+		CapWorkspaceSelect,
+	}
+	sort.Strings(out)
+	return out
+}
+
+// CapabilitiesOf 返回某个引擎**静态声明**的能力 id 集合（字典序，稳定、无重复）。
+//
+// 未注册的引擎名返回 nil —— 调用方据此区分「没这个引擎」与「这个引擎什么都不会」
+// （后者在当前实现里不可能出现：所有内置引擎至少支持 workspace 或附件降级）。
+func CapabilitiesOf(engine string) []string {
+	e := Lookup(engine)
+	if e == nil {
+		return nil
+	}
+	return capabilitiesOfEngine(e)
+}
+
+// capabilitiesOfEngine 按引擎实例推导能力（CapabilitiesOf 的实现）。
+//
+// 单独拆出来是为了让用例能直接拿引擎实例断言，**不必依赖包级注册表的全局状态** ——
+// 注册表有个已知脆弱点（Engines() 之前被 Register 过就不注册内置引擎，见 engine.go），
+// 而按名筛选测试时它会让「按名字查表」的结果凭空消失。
+func capabilitiesOfEngine(e Engine) []string {
+	name := e.Name()
+	var caps []string
+	add := func(id string) { caps = append(caps, id) }
+
+	if AsStreamer(e) != nil {
+		add(CapSessionStream)
+	}
+	if AppendSupportOf(name) {
+		add(CapSessionAppend)
+	}
+	if !unsupported(AskSupportOf(name)) {
+		add(CapSessionAsk)
+	}
+	if !unsupported(PermissionSupportOf(name)) {
+		add(CapSessionPermission)
+	}
+	if !unsupported(WorkspaceSupportOf(name)) {
+		add(CapWorkspaceSelect)
+	}
+	switch AttachmentSupportOf(name) {
+	case "prompt":
+		add(CapAttachmentPrompt)
+	case "", "none":
+		// 无附件通道：不加任何附件能力。
+	default:
+		add(CapAttachmentNative)
+	}
+	if ModelListerOf(e) != nil {
+		add(CapModelList)
+	}
+	if _, ok := e.(ModelCreditLister); ok {
+		add(CapModelCredits)
+	}
+	if InstallCommandOf(name) != "" {
+		add(CapEngineInstall)
+	}
+
+	sort.Strings(caps)
+	return caps
+}
+
+// unsupported 判断一张能力表的取值是否表示「没有这条通道」。
+// 空串与 "none" 都算没有 —— 两张表历史上两种写法都出现过，这里统一兜住。
+func unsupported(v string) bool {
+	return v == "" || v == "none"
+}
+
+/* 核心级能力 id：不属于任何单个引擎，而是 core 自己提供的**通道**。
+ *
+ * 与引擎能力分开命名（`feature.` 前缀）与分开返回：客户端要回答的是两个不同问题 ——
+ * 「这个引擎能做什么」（engines[].capabilities）与「这台机器上的 core 支不支持这条通道」
+ * （features）。混在一个集合里会让前者随 core 升级而无故变化。
+ */
+
+const (
+	// FeatureSessionEvents `--stream --events`：事件流带契约版本与行号，并先发一行 ready。
+	FeatureSessionEvents = "feature.session.events"
+	// FeatureSessionControl `--stream --control`：stdin NDJSON 控制通道（打断 / 收工 / 回审批）。
+	FeatureSessionControl = "feature.session.control"
+)
+
+// CoreFeatures 返回 core 自身提供的通道能力（字典序，稳定）。
+func CoreFeatures() []string {
+	return []string{FeatureSessionControl, FeatureSessionEvents}
+}

package/internal/agent/capability_test.go

@@ -0,0 +1,190 @@
+package agent
+
+import (
+	"sort"
+	"strings"
+	"testing"
+)
+
+// hasCap 判断能力列表里有没有某个 id。
+func hasCap(caps []string, id string) bool {
+	for _, c := range caps {
+		if c == id {
+			return true
+		}
+	}
+	return false
+}
+
+// TestCapabilitiesOfAllEngines 注册表里每个引擎的能力列表都要**结构合法**：
+// 有序、无重复、id 都在已知集合里。
+//
+// 刻意不要求「非空」，也不检查注册表里有多少个引擎：注册表里可能出现用例注册的
+// 探针引擎（它什么都没声明），而且它有个已知脆弱点会让内置引擎在某些运行方式下
+// 整体缺席（见 engine.go 的 registry 注释）。「真实引擎至少有一项能力」由
+// TestCapabilitiesDocumentedEngines 用**直接构造的实例**断言，与注册表状态无关。
+func TestCapabilitiesOfAllEngines(t *testing.T) {
+	known := map[string]bool{}
+	for _, id := range CapabilityIDs() {
+		known[id] = true
+	}
+	engines := Engines()
+	if len(engines) == 0 {
+		t.Fatal("引擎注册表为空，能力推导无从校验")
+	}
+	for _, e := range engines {
+		caps := CapabilitiesOf(e.Name())
+		if !sort.StringsAreSorted(caps) {
+			t.Errorf("%s: 能力列表未排序: %v", e.Name(), caps)
+		}
+		seen := map[string]bool{}
+		for _, id := range caps {
+			if seen[id] {
+				t.Errorf("%s: 能力重复: %s", e.Name(), id)
+			}
+			seen[id] = true
+			if !known[id] {
+				t.Errorf("%s: 未知能力 id %q（新增能力要同时进 CapabilityIDs）", e.Name(), id)
+			}
+		}
+	}
+}
+
+// TestCapabilitiesOfUnknownEngine 未注册的引擎名返回 nil —— 调用方据此区分
+// 「没这个引擎」与「这个引擎什么都不会」。
+func TestCapabilitiesOfUnknownEngine(t *testing.T) {
+	if caps := CapabilitiesOf("no-such-engine-xyz"); caps != nil {
+		t.Errorf("未注册引擎应返回 nil，得到 %v", caps)
+	}
+	if caps := CapabilitiesOf(""); caps != nil {
+		t.Errorf("空名字应返回 nil，得到 %v", caps)
+	}
+}
+
+// TestCapabilitiesStable 多次调用结果逐项一致：capabilities 是**静态声明**，
+// 不应受运行态（是否冷却、模型探测成功与否）影响。
+func TestCapabilitiesStable(t *testing.T) {
+	for _, e := range Engines() {
+		a := CapabilitiesOf(e.Name())
+		b := CapabilitiesOf(e.Name())
+		if len(a) != len(b) {
+			t.Errorf("%s: 两次调用长度不同 %d vs %d", e.Name(), len(a), len(b))
+			continue
+		}
+		for i := range a {
+			if a[i] != b[i] {
+				t.Errorf("%s: 第 %d 项不稳定 %q vs %q", e.Name(), i, a[i], b[i])
+			}
+		}
+	}
+}
+
+// TestCapabilitiesDocumentedEngines 钉住 README 里已经写明的几条推导，防止把
+// 「原生通道」与「降级通道」写反。
+//
+// 用**直接构造的引擎实例**（capabilitiesOfEngine），不走按名字查表 —— 注册表有全局状态，
+// 会随测试筛选方式变化（见 engine.go 的 registry 注释），而这几条事实与注册表无关。
+func TestCapabilitiesDocumentedEngines(t *testing.T) {
+	// claude：stream / ask（AskUserQuestion + can_use_tool）/ 四档权限 / 原生附件 / npm 安装命令
+	claude := capabilitiesOfEngine(&ClaudeEngine{})
+	if len(claude) == 0 {
+		t.Fatal("claude 的能力列表为空（真实引擎至少应有一项）")
+	}
+	for _, id := range []string{
+		CapSessionStream, CapSessionAsk, CapSessionPermission,
+		CapAttachmentNative, CapEngineInstall,
+	} {
+		if !hasCap(claude, id) {
+			t.Errorf("claude 应有能力 %s，实际 %v", id, claude)
+		}
+	}
+
+	// llm：README 明确「其余引擎」没有 ask / permission 通道
+	llm := capabilitiesOfEngine(&LLMEngine{})
+	for _, id := range []string{CapSessionAsk, CapSessionPermission} {
+		if hasCap(llm, id) {
+			t.Errorf("llm 不应有能力 %s，实际 %v", id, llm)
+		}
+	}
+
+	// codebuddy 系 2026-09-28 起改成**独立安装**的 CodeBuddy Code CLI
+	//（不再是桌面 GUI 应用）→ 有可执行安装路径，因此有 engine.install。
+	for _, e := range []Engine{&CodeBuddyEngine{}, &CodeBuddyAIEngine{}} {
+		if cb := capabilitiesOfEngine(e); !hasCap(cb, CapEngineInstall) {
+			t.Errorf("%s 应有能力 %s（npm 一键安装命令），实际 %v", e.Name(), CapEngineInstall, cb)
+		}
+	}
+	// 反例：没有可执行安装路径的引擎不给 engine.install
+	//（codebuddy-gateway 要的不是安装，而是「把网关跑起来」）。
+	if gw := capabilitiesOfEngine(&CodeBuddyGatewayEngine{}); hasCap(gw, CapEngineInstall) {
+		t.Errorf("codebuddy-gateway 不应有能力 %s（无安装命令），实际 %v", CapEngineInstall, gw)
+	}
+
+	// 走路径降级的引擎：给 attachment.prompt 而不是 attachment.native
+	for _, tc := range []struct {
+		name string
+		e    Engine
+	}{
+		{"trae", &TraeEngine{}},
+		{"openclaw", &OpenClawEngine{}},
+		{"dsh", &DshEngine{}},
+	} {
+		caps := capabilitiesOfEngine(tc.e)
+		if !hasCap(caps, CapAttachmentPrompt) {
+			t.Errorf("%s 应有能力 %s（附件走提示词路径），实际 %v", tc.name, CapAttachmentPrompt, caps)
+		}
+		if hasCap(caps, CapAttachmentNative) {
+			t.Errorf("%s 不应有能力 %s，实际 %v", tc.name, CapAttachmentNative, caps)
+		}
+	}
+
+	// arkclaw 的附件走 A2A 原生 file part → 应给出 attachment.native。
+	// 这条直接查表：ArkClawEngine 的名字来自配置（不是常量），不适合直接构造。
+	if got := AttachmentSupportOf("arkclaw"); got != "part:file" {
+		t.Errorf("arkclaw attachments = %q want part:file（原生 file part → attachment.native）", got)
+	}
+}
+
+// TestCoreFeaturesSorted 核心级通道能力要干净可用（客户端拿它判断 core 支不支持某条通道）。
+func TestCoreFeaturesSorted(t *testing.T) {
+	f := CoreFeatures()
+	if len(f) == 0 {
+		t.Fatal("CoreFeatures 为空")
+	}
+	if !sort.StringsAreSorted(f) {
+		t.Errorf("CoreFeatures 未排序: %v", f)
+	}
+	for i := 1; i < len(f); i++ {
+		if f[i] == f[i-1] {
+			t.Errorf("CoreFeatures 有重复项: %s", f[i])
+		}
+	}
+	for _, want := range []string{FeatureSessionEvents, FeatureSessionControl} {
+		if !hasCap(f, want) {
+			t.Errorf("CoreFeatures 缺 %s，实际 %v", want, f)
+		}
+	}
+	// 核心级能力不能混进引擎能力白名单（两者是两个问题）。
+	for _, id := range CapabilityIDs() {
+		if strings.HasPrefix(id, "feature.") {
+			t.Errorf("CapabilityIDs 不应含核心级能力 %q", id)
+		}
+	}
+}
+
+// TestCapabilityIDsDedupedAndSorted 能力全集本身要干净：无重复、已排序
+// （客户端与服务端都可能拿它做校验白名单）。
+func TestCapabilityIDsDedupedAndSorted(t *testing.T) {
+	ids := CapabilityIDs()
+	if len(ids) == 0 {
+		t.Fatal("CapabilityIDs 为空")
+	}
+	if !sort.StringsAreSorted(ids) {
+		t.Errorf("CapabilityIDs 未排序: %v", ids)
+	}
+	for i := 1; i < len(ids); i++ {
+		if ids[i] == ids[i-1] {
+			t.Errorf("CapabilityIDs 有重复项: %s", ids[i])
+		}
+	}
+}