拆解 Warp AI Agent（五）：跨生态联邦——10 种 Skill + MCP + 多 Harness 互操作设计

系列终篇。前四篇讲了类型安全、风险调度、对话状态机、增量索引------都是 Warp 自身的架构。本篇看 Warp 如何与外部世界互联：10 种 Skill Provider、MCP 协议、多 Harness Bridge，构成一个"AI Agent 联邦"。

---

一、问题：为什么 AI Agent 需要互操作？

2025-2026 年的 AI Agent 生态是碎片化的：

Claude Code → .claude/skills/ → Claude API
Cursor      → .cursor/skills/ → 自研 API
Codex       → .codex/skills/  → OpenAI API
Gemini      → .gemini/skills/ → Google API
Copilot     → .copilot/skills/ → GitHub API
Warp        → .warp/skills/   → Warp API

每个工具有自己的 Skill 目录、自己的 Agent 引擎、自己的工具链。用户的问题是：

我在 Claude Code 里写的 Skill，能在 Warp 里用吗？

Warp 的答案是：能，而且优先级可配置。

---

二、10 种 Skill Provider：优先级联邦

2.1 Provider 定义

// crates/ai/src/skills/skill_provider.rs
pub enum SkillProvider {
    Warp,
    Agents,
    Claude,
    Codex,
    Cursor,
    Gemini,
    Copilot,
    Droid,
    Github,
    OpenCode,
}

2.2 优先级排序

pub static SKILL_PROVIDER_DEFINITIONS: LazyLock<Vec<SkillProviderDefinition>> =
    LazyLock::new(|| {
        vec![
            // 优先级从高到低
            SkillProviderDefinition { provider: SkillProvider::Agents, skills_path: PathBuf::from(".agents/skills") },
            SkillProviderDefinition { provider: SkillProvider::Warp,   skills_path: PathBuf::from(".warp/skills") },
            SkillProviderDefinition { provider: SkillProvider::Claude, skills_path: PathBuf::from(".claude/skills") },
            SkillProviderDefinition { provider: SkillProvider::Codex,  skills_path: PathBuf::from(".codex/skills") },
            SkillProviderDefinition { provider: SkillProvider::Cursor, skills_path: PathBuf::from(".cursor/skills") },
            SkillProviderDefinition { provider: SkillProvider::Gemini, skills_path: PathBuf::from(".gemini/skills") },
            SkillProviderDefinition { provider: SkillProvider::Copilot,skills_path: PathBuf::from(".copilot/skills") },
            SkillProviderDefinition { provider: SkillProvider::Droid,  skills_path: PathBuf::from(".factory/skills") },
            SkillProviderDefinition { provider: SkillProvider::Github, skills_path: PathBuf::from(".github/skills") },
            SkillProviderDefinition { provider: SkillProvider::OpenCode,skills_path: PathBuf::from(".opencode/skills") },
        ]
    });

优先级规则：同名 Skill，排在前的 Provider 优先。也就是说：

1. .agents/skills/ 的 Skill 优先级最高（项目级、通用标准）
2. .warp/skills/ 其次（Warp 特定）
3. .claude/skills/ 再次（Claude 兼容）
4. ...依次类推

2.3 自动识别

pub fn get_provider_for_path(path: &Path) -> Option<SkillProvider> {
    let path_components: Vec<_> = path.components().collect();
    for def in SKILL_PROVIDER_DEFINITIONS.iter() {
        // 检查路径中是否包含该 Provider 的目录
        let skill_components: Vec<_> = def.skills_path.components().collect();
        for window in path_components.windows(skill_components.len()) {
            if window == skill_components.as_slice() {
                return Some(def.provider);
            }
        }
    }
    None
}

效果 ：把一个 .claude/skills/my-skill/SKILL.md 文件丢给 Warp，Warp 自动识别它来自 Claude，加载时打上 SkillProvider::Claude 标签。

2.4 Scope 区分

pub enum SkillScope {
    /// 用户主目录下的 Skill (e.g. ~/.agents/skills)
    Home,
    /// 项目目录下的 Skill (e.g. ./repo/.agents/skills)
    Project,
    /// Warp 内置 Skill
    Bundled,
}

三重作用域：Home（全局） > Project（项目） > Bundled（内置）。项目级 Skill 覆盖全局 Skill，类似于 .gitignore 的层叠规则。

---

三、项目上下文双文件规则：WARP.md + AGENTS.md

3.1 为什么是两个文件？

// crates/ai/src/project_context/model.rs
const RULES_FILE_PATTERN: [&str; 2] = ["WARP.md", "AGENTS.md"];

• WARP.md --- Warp 特定的规则（终端操作偏好、Agent 行为配置）
• AGENTS.md --- 通用 Agent 规则（跨工具兼容，Claude Code / Codex / Cursor 都能读）

类似于 .github/ 和 .agents/ 的关系：一个是平台特定的，一个是跨平台通用的。

3.2 层叠累积

/                          → WARP.md (全局规则)
/project/                  → WARP.md + AGENTS.md (项目规则)
/project/src/              → WARP.md + AGENTS.md (src 子目录规则)
/project/src/components/   → WARP.md (组件特定规则)

struct RuleAtPath {
    parent_path: PathBuf,
    warp_md: Option<ProjectRule>,    // WARP.md
    agents_md: Option<ProjectRule>,  // AGENTS.md
}

fn find_active_or_applicable_rules(&self, path: &Path) -> FindRulesResult {
    let mut active_rules = Vec::new();
    let mut available_rule_paths = Vec::new();

    for rule in &self.rules {
        if let Some(respected_rule) = rule.respected_rule() {
            // 目标路径在该规则的父目录下 → 活跃规则
            if path.starts_with(&rule.parent_path) {
                active_rules.push(respected_rule.clone());
            } else {
                // 否则 → 可用但未激活
                available_rule_paths.push(respected_rule.path.to_string_lossy().to_string());
            }
        }
    }
    // ...
}

关键区分：

• Active Rules --- 当前文件路径的祖先目录中的规则，自动注入 Agent 上下文
• Available Rules --- 其他目录的规则，只有相关时才加载（如编辑该目录下的文件时）

这解决了"规则太多撑爆 Token 窗口"的问题------只加载与当前工作相关的规则。

---

四、MCP 协议：4 种 Provider

// app/src/ai/mcp/mod.rs
pub enum MCPProvider {
    Warp,    // Warp 自有配置
    Claude,  // Claude Desktop 兼容
    Codex,   // Codex 兼容
    Agents,  // 通用 Agents 兼容
}

4.1 多格式配置解析

Warp 能读取多种 MCP 配置格式：

来源	配置文件路径	格式
Warp 自有	~/.warp/mcp_config.json	Warp 格式
Claude Desktop	~/.claude/claude_desktop_config.json	Claude 格式
VS Code	.vscode/mcp.json	VS Code 格式
项目级	.mcp.json	标准 MCP 格式

4.2 Transport 类型

pub enum TransportType {
    /// 标准输入输出 (CLI Server)
    CLIServer,
    /// Server-Sent Events
    ServerSentEvents,
}

4.3 模板变量

MCP Server 配置支持模板变量，比如环境变量注入：

{
  "mcpServers": {
    "my-server": {
      "command": "my-mcp-server",
      "env": {
        "API_KEY": "{{API_KEY}}"
      }
    }
}

Warp 会自动提取 {``{API_KEY}} 模板变量，在启动 MCP Server 时从用户的 Secret 管理器中注入。

---

五、Multi-Harness Bridge：Agent SDK 的联邦枢纽

5.1 三层 Harness 架构

┌──────────────────────────────────────────┐
│         CLI 层: Harness enum              │
│   Oz / Claude / Gemini / OpenCode         │
├──────────────────────────────────────────┤
│         对话层: AIAgentHarness enum        │
│   Oz / ClaudeCode / Gemini / Unknown      │
├──────────────────────────────────────────┤
│         驱动层: HarnessKind enum           │
│   Oz / ThirdParty(dyn HarnessRunner)       │
│                / Unsupported               │
└──────────────────────────────────────────┘

5.2 ThirdPartyHarness trait

// app/src/ai/agent_sdk/driver/harness/mod.rs
#[cfg_attr(not(target_family = "wasm"), async_trait)]
pub trait ThirdPartyHarness: Send + Sync {
    fn harness(&self) -> Harness;
    fn cli_agent(&self) -> CLIAgent;
    fn install_url(&self) -> &'static str;

    /// 校验 Harness 是否就绪（默认检查 CLI 是否在 PATH 上）
    async fn validate(&self) -> Result<(), AgentDriverError>;

    /// 准备 CLI 特定的配置文件
    fn prepare_environment_config(&self, ...) -> Result<()>;

    /// 获取恢复对话所需的 payload
    async fn fetch_resume_payload(&self, ...) -> Result<Option<ResumePayload>>;

    /// 构建运行器
    async fn build_runner(&self, ...) -> Result<Box<dyn HarnessRunner>>;
}

5.3 HarnessRunner trait

pub(crate) trait HarnessRunner: Send + Sync {
    /// 启动 Harness（在终端中执行 CLI 命令）
    async fn start(&self, foreground: &ModelSpawner<AgentDriver>) -> Result<CommandHandle>;

    /// 保存对话状态
    async fn save_conversation(&self, save_point: SavePoint, ...) -> Result<()>;

    /// 优雅退出
    async fn exit(&self, foreground: &ModelSpawner<AgentDriver>) -> Result<()>;

    /// 清理后台状态
    async fn cleanup(&self, foreground: &ModelSpawner<AgentDriver>) -> Result<()>;
}

5.4 Bridge 路由

fn harness_kind(harness: Harness) -> Result<HarnessKind, AgentDriverError> {
    match harness {
        Harness::Oz => Ok(HarnessKind::Oz),
        Harness::Claude => Ok(HarnessKind::ThirdParty(Box::new(ClaudeHarness))),
        Harness::Gemini => Ok(HarnessKind::ThirdParty(Box::new(GeminiHarness))),
        Harness::OpenCode => Ok(HarnessKind::Unsupported(Harness::OpenCode)),
        Harness::Unknown => Err(AgentDriverError::InvalidRuntimeState),
    }
}

关键设计 ：HarnessKind::ThirdParty(Box<dyn ThirdPartyHarness>) --- 用 trait object 实现运行时多态。新增一个 Harness 只需要实现 ThirdPartyHarness trait，不需要修改路由代码。

5.5 对话恢复

pub enum ResumeOptions {
    Oz(Box<ConversationRestorationInNewPaneType>),
    ThirdParty(Box<ResumePayload>),
}

Oz Harness 恢复对话时，直接还原完整对话转录到终端 pane；第三方 Harness 则使用 harness-specific payload（如 Claude 的 session ID）。

---

六、Cloud MCP 同步：跨设备配置共享

设备 A 添加 MCP Server
    → Warp Drive 同步队列
    → 云端存储
    → 设备 B 下行同步
    → 自动加载新 MCP Server

MCP 配置可以通过 Warp Drive 云同步，实现跨设备共享。这是 Warp 作为云原生终端的独特优势。

---

七、与业界方案对比

维度	Warp	Claude Code	Cursor	GitHub Copilot
Skill 跨工具兼容	10 Provider	仅 Claude	仅 Cursor	无
项目规则	WARP.md + AGENTS.md	CLAUDE.md	.cursorrules	无
MCP 支持	4 Provider 配置源	仅 Claude	部分	无
外部 Agent	Claude/Gemini/OpenCode CLI	无	无	无
配置云同步	Warp Drive	无	无	无

Warp 是唯一同时支持跨工具 Skill 兼容 + 外部 Agent CLI 委托 + MCP 多源配置的终端 Agent。

---

八、可复用模式：Cross-Ecosystem Federation

┌─────────────────────────────────────────┐
│    Cross-Ecosystem Federation            │
├─────────────────────────────────────────┤
│ 1. 优先级联邦                            │
│    - 多 Provider 按优先级排序            │
│    - 同名 Skill 取最高优先级             │
│    - 自动识别 Provider 来源              │
│                                          │
│ 2. 双文件规则                            │
│    - 平台特定: WARP.md                   │
│    - 跨平台通用: AGENTS.md               │
│    - 层叠累积 + 按需加载                 │
│                                          │
│ 3. MCP 多源                              │
│    - 多格式配置解析                      │
│    - 模板变量自动注入                    │
│    - 云端配置同步                        │
│                                          │
│ 4. Harness Bridge                        │
│    - trait object 运行时多态             │
│    - 新增 Harness 零修改路由代码         │
│    - 对话恢复按 Harness 类型分派         │
└─────────────────────────────────────────┘

---

九、系列总结：七个架构模式

#	模式	核心价值	通用度
1	Type-Driven Tool Protocol	编译期工具类型安全	★★★ (需要 ADT 语言)
2	Exhaustive Cancellation	新增 Action 不遗漏取消处理	★★★
3	Risk-Graded Execution	只读并行 + 危险串行	★★★★
4	Conversation State Machine	五态模型管理对话生命周期	★★★★
5	LRC Dual-Mode	Agent↔用户交替控制长时命令	★★ (终端特有)
6	Merkle Tree Index	O(changes) 增量索引	★★★★★
7	Cross-Ecosystem Federation	10 Provider + MCP + Harness 互操作	★★★★

通用度最高的三个（可直接落地到任何 Agent 项目）：

1. Risk-Graded Execution --- 任何 Agent 都需要区分安全和危险操作
2. Merkle Tree Index --- 任何需要索引代码库的 Agent 都能受益
3. Cross-Ecosystem Federation --- 越来越多 Agent 工具需要互操作

Warp 最独特的设计：LRC Dual-Mode（长时命令双模控制）------这是终端 Agent 独有的需求，IDE Agent 不需要。

---

十、给 Agent 构建者的建议

1. 工具协议优先用类型系统，不管什么语言，只要能穷举就用穷举
2. 只读操作一定要并行，这是最简单的性能提升
3. 对话状态设计成状态机，而不是 if-else 堆砌
4. 代码索引用 Merkle Tree，比轮询快一个数量级
5. Skill/规则要跨工具兼容，AGENTS.md 比 CLAUDE.md 更通用
6. 配置要能云同步，跨设备体验是刚需

一句话总结：Warp 的 AI Agent 是一个"联邦"------10 种 Skill Provider 联盟、4 种 MCP 配置源聚合、3 种 Harness 引擎桥接，所有外部工具都在同一个优先级体系下运行。

---

系列导航：

• （一）类型即协议
• （二）风险分级执行
• （三）对话状态机
• （四）Merkle Tree 增量索引
• （五）跨生态联邦 ← 你在这里