AI Agent 环境兼容性 SDK 设计思路

AI 编码工具越来越需要项目特定的指令、规则和清单文件（manifest）。难点在于每个环境可能期望不同的原生表现形式。本文介绍 agent-compat 的架构设计：检测、基于适配器的编译、原生输出和验证。

一个项目可能需要将相同的意图传达给多个 AI Agent 环境。这些环境在文件名、目录结构、支持字段和约定方面可能有所不同。

简单的解决方案是手动维护每个原生文件。

但这种方案会产生漂移（drift）。

我为 agent-compat 设计了一种类似编译器的工作流程，包含四个步骤：

detect → compile → write native files → validate

源清单文件（source manifest）代表项目意图。适配器（adapter）将该意图翻译成目标环境所期望的表现形式。验证环节随后根据规范检查生成的结果。

为什么检测至关重要

手动指定目标需要用户始终了解当前存在哪种环境以及应该生成哪些目标文件。自动检测能够降低这种协调成本，使集成更容易嵌入到工作流程中。

检测不应与编译相混淆。系统首先确定上下文，然后选择适当的适配器和输出策略。

不应将每个环境硬编码到核心工作流程中。适配器将目标特定的行为隔离开来：

输出转换

开放的注册表也为社区维护的适配器提供了支持路径。

为什么验证是一等的

没有验证的生成只是完整工作流程的一半。

生成的文件可能存在但仍然不完整或已过期。验证 API 使得兼容性可以在代码中测试，并在 CI 中使用。

一份有用的报告应该能帮助回答：

• 检测到了哪个目标？
• 生成了哪些文件？
• 哪些字段或输出与规范不同？

SDK 与 CLI

CLI 对直接的人机交互很方便。当另一个系统需要以编程方式调用兼容性功能时，SDK 更有用。

这就是为什么 agent-compat 采用库优先的设计。它可以嵌入到开发者工具、仓库自动化和 CI 流水线中，而配套的 CLI 则提供简洁的终端界面。

输出应该是原生文件，而不是每个下游工具都必须理解的抽象兼容层。原生输出使结果贴近目标环境，而验证报告则保留了对执行过程的可见性。

早期版本

agent-compat 目前是一个采用 MIT 许可证的早期开源项目。首个版本的目标是建立模型，并通过实际使用发现真正的兼容性问题。

仓库地址：https://github.com/JustineDevs/agent-compat

npm install @jstn-sdk/agents

import { Agents } from "@jstn-sdk/agents";

自动发现项目中存在哪些 Agent 环境：

const detected = await Agents.detect("./my-project");
// → [{ id: "cursor", confidence: 0.95 }, { id: "codex-cli", confidence: 0.92 }]

将规范清单转换为每个环境的原生文件：

const manifest = {
  version: 1,
  project: { name: "my-app", stack: ["typescript"] },
  instructions: ["Run tests before completion"],
  skills: { "code-review": { description: "Review PRs" } }
};

const result = await Agents.compile(manifest, {
  targets: ["cursor", "codex-cli", "pi"],
  output: "./my-project"
});
// → { files: [".cursor/rules/agents.mdc", "AGENTS.md", ".pi/skills/review/SKILL.md"] }

根据官方规范检查生成的文件：

const report = await Agents.validate("./my-project");
// → { cursor: "✓", "codex-cli": "✓", pi: "◐", summary: { ... } }

如果你在多个 AI 工具中维护指令，一个兼容性 SDK 首先应该验证什么：文件存在性、schema 正确性、语义等价性，还是随时间的漂移？