开放智能体生态下的可移植性设计：Open Interpreter 如何践行共享 Agent 标准

Open Interpreter 是一个面向开放模型（如 Kimi K3、GLM 5.3 等）的编码 Agent，它的一个重要产品与工程约束是：不做一个"指令、技能与工作流的孤岛"，而是尽可能参与共享的 Agent 生态系统——凡是存在业界通用的跨工具标准，就直接读取并保留为标准形态，让用户的数据可以被其他兼容工具直接复用。本文基于仓库文档 docs/portability.md，系统拆解这套可移植性（Portability）策略的六条原则、当前的共享协议面（AGENTS.md、.agents/skills、MCP、ACP、exec 协议）、产品私有状态边界以及新增文件格式时的判断准则；读完你将理解 Open Interpreter 中"用户数据放哪里、为何这样放、如何不锁定用户"的完整设计逻辑。

可移植性的定位：一个产品方向，也是一条工程约束

docs/portability.md 开篇即明确：Open Interpreter 的目标是参与共享的 Agent 生态，而不是制造一个封闭的私有世界。这里的关键表述是：

当存在实用的跨工具标准时，Open Interpreter 应当直接读取该标准，并以其他兼容工具也能使用的形态去保留它。

文档同时非常克制地划定了边界——这是一个产品方向与工程约束，并非声称每一种运行时状态都已经具备通用格式。也就是说，"能共享的尽量共享、暂不能共享的诚实保留为产品状态"是可移植性设计的两面。

从工程落地看，这一方向并非停留在文档口号。仓库内大量模块都围绕"读取共享标准"与"兼容历史路径"展开：指令文件解析集中在 codex-rs/core/src/agents_md.rs，技能目录的分层发现与选择逻辑位于 codex-rs/skills 的多个 crate 中。下文将按文档脉络逐一展开。

六条原则：可移植性判断的底层依据

docs/portability.md 给出了判断一切变更是否"可移植"的六条原则，它们是整篇文档的灵魂：

1. 优先采用已确立的、工具无关的协议与目录约定，而不是 Open Interpreter 私有的等价物；
2. 保持用户撰写的指令、技能与配置可读、可检查（readable and inspectable）；
3. 就地读取共享内容（read in place），而不是要求导入或制作一份私有拷贝；
4. 在迁移期间为历史产品路径保留兼容性读取器；
5. 当尚无共享的活格式（shared live format）时，保证导出与迁移的可能性；
6. 将产品特定存储（product-specific storage）保留给密钥、缓存、索引、日志以及尚无法被共享标准安全表示的运行时状态。

这套原则的内在逻辑值得强调：标准化的对象是用户撰写的资产（指令、技能、配置），而密钥、缓存、索引、日志这类机器生成或高度依赖运行时实现的状态，则被明确允许留在产品私有空间。换言之，Open Interpreter 承诺"不锁死用户能看懂、能带走的内容"，同时不假装一切都能标准化。

当前共享面（Shared Surface）：五个标准协议与目录约定

docs/portability.md 以一张表格给出了当前已经采纳的共享面：

能力（Capability）	共享面（Shared surface）
项目指令（Project instructions）	AGENTS.md
项目技能（Project skills）	.agents/skills/
个人技能（Personal skills）	~/.agents/skills/
工具集成（Tool integrations）	Model Context Protocol（MCP）
编辑器与客户端集成	Agent Client Protocol（ACP）
编程式执行（Programmatic execution）	Codex 兼容的 exec 协议

文档强调：这些位置与协议应当在不把用户数据转换为 Open Interpreter 专属表示的前提下正常工作。下面结合仓库实现逐一展开。

项目指令 AGENTS.md：从仓库根到当前目录的分层读取

AGENTS.md 是事实上的行业共享约定，Open Interpreter 把它作为项目指令的载体。其配套说明见 docs/agents_md.md：指令应在仓库根放置一个 AGENTS.md，承载构建、测试、lint、格式化命令、架构说明、代码风格约定等稳定信息，而不必在每次对话中重复。在 TUI 中可以直接输入 /init 让 Open Interpreter 扫描仓库并起草一份初始版本。

从源码看，这一读取逻辑实现在 codex-rs/core/src/agents_md.rs：

• 默认扫描文件名为 AGENTS.md（DEFAULT_AGENTS_MD_FILENAME），本地覆盖文件为 AGENTS.override.md（LOCAL_AGENTS_MD_FILENAME），见 agents_md.rs#L36-L39；
• 指令发现采用分层方式：收集从项目根目录一直到当前工作目录（cwd）沿途的所有 AGENTS.md，越靠近当前目录的文档被认为越相关；仓库自身的顶层 AGENTS.md 就是一个可对照的真实样例；
• 用户级与项目级文档拼接时以 \n\n--- project-doc ---\n\n 分隔（AGENTS_MD_SEPARATOR）；
• 全局与项目指令的总大小由 project_doc_max_bytes 配置上限控制，当预算耗尽时会优先保留距离当前目录更近的文件；当该配置为 0 时整个 AGENTS.md 读取被禁用（见 agents_md.rs#L94-L98）。

用户还可以通过创建 ~/.openinterpreter/AGENTS.override.md 临时替换全局指令用于本地测试，删除该文件即恢复。这套机制保证：项目级指令以"每个人都能直接阅读的 Markdown"形式存在于仓库里，而非封装进私有数据格式。

技能体系：.agents/skills/ 共享目录与 ~/.openinterpreter/skills/ 历史兼容

技能是可复用工作流、参考资料、脚本与资产的打包单元。仓库文档 docs/skills.md 规定：一个技能就是一个包含 SKILL.md（必需）以及可选 scripts/、references/、assets/ 子目录的文件夹；Open Interpreter 先读取技能元数据，仅当请求匹配时才加载完整技能。

技能的三层位置（在 docs/skills.md 与可移植性文档中一致）是：

路径	范围
.agents/skills/	仓库或目录级（项目）技能
~/.agents/skills/	个人技能
内置技能（bundled skills）	随产品交付的工作流

名称冲突时，本地技能优先于个人技能与内置技能。与可移植性直接相关的设计是：新技能应放在 .agents/skills/ 这些工具无关的共享目录，这样另一个兼容 Agent 无需经过 Open Interpreter 的导入或复制即可使用同一技能；而旧的 ~/.openinterpreter/skills/ 目录仅作为历史兼容回退被继续读取，避免既有环境被破坏，但不再建议把新技能写进这个产品私有目录（内置技能因属于产品资产而非可移植的用户数据，仍可缓存在 Open Interpreter 主目录下）。

仓库对这套共享目录约定的支撑非常充分：

• 技能 crate codex-rs/skills 负责 SKILL.md 的解析（parser.rs）、选择（selection.rs）与调用，其中 selection_tests.rs 直接以 /tmp/project/.agents/skills/linked-skill/SKILL.md 这类路径构造测试，验证了共享目录形态是核心数据模型而非旁支；
• 端到端测试同样以项目内技能为对象，例如 codex-rs/core/tests/suite/skills.rs 会在 cwd.join(".agents/skills/demo/SKILL.md") 与 cwd.join(".agents/skills/queued-demo") 位置创建技能并验证其被发现、排队与执行；
• 扩展机制测试 skills_extension.rs 进一步验证了"用户层还会发现真实 $HOME/.agents/skills"这一行为。

工具集成：走 MCP 而非私有工具协议

工具集成共享面是 Model Context Protocol（MCP）。可移植性的含义在于：Open Interpreter 自身并非外部工具的唯一供应商，问题追踪器、私有文档、数据库、内部 CLI 等能力应当通过 MCP 服务器显式接入。具体配置方式见 docs/mcp.md：在 ~/.openinterpreter/config.toml 中声明 stdio 或 HTTP 服务器、审批模式（prompt/approve/auto）、工具过滤（enabled_tools/disabled_tools）等；也可用 interpreter mcp add/list/get/remove/login/logout 命令行管理，TUI 内用 /mcp 查看已加载服务器。服务端实现位于 codex-rs/mcp-server，协议细节可参考 docs/mcp-server.md。由于 MCP 本身是工具无关的开放协议，用户接好的 MCP 工具配置原则上同样适用于其他支持 MCP 的客户端。

编辑器 / 客户端集成：ACP

编辑器与客户端集成的共享面是 Agent Client Protocol（ACP），Open Interpreter 作为 ACP 端点接入编辑器/客户端生态，用户不必学习 Open Interpreter 私有的接入格式。协议工作方式可参见 docs/acp.md，底层协议定义位于 codex-rs/app-server-protocol。

编程式执行：Codex 兼容的 exec 协议

编程式执行场景采用 Codex 兼容的 exec 协议，而不是自创一套仅供自身 SDK 使用的执行格式。相关说明见 docs/exec.md；具体实现分布在 codex-rs/exec（执行策略与 exec 客户端）与 codex-rs/exec-server（受控执行服务，含沙箱）。这也解释了仓库中大量 exec 集成测试的由来——协议本身的兼容性是"另一个工具能驱动同一执行后端"的前提。

产品特定状态（Product-Specific State）：什么留在 ~/.openinterpreter，什么将来可能迁走

可移植性并不等于消灭所有私有状态。docs/portability.md 明确列出当前保留在 ~/.openinterpreter 或操作系统凭据库（credential store）中的内容：配置、凭据、会话历史、日志、缓存与守护进程（daemon）状态。

文档对这一划分给出了清醒的两点说明：

• 其中一部分状态本质上是产品特定的（product-specific）；
• 另一些则可能在某个安全且被广泛采纳的共享标准出现后迁往共享格式。

因此这是一个"分阶段、看时机"的取舍：在没有可靠共享格式之前，先老老实实把状态放在自家目录并保证可导出，比勉强塞进一个不成熟的标准更负责。同时，~/.openinterpreter/skills/ 这一历史技能目录仍保持可读，作为兼容路径；而共享的 ~/.agents/skills/ 才是个人新技能的推荐归属——这也再次呼应了原则四（迁移期保留兼容读取器）与原则六（私有存储只留给尚不能共享的状态）。

对变更的约束：新增产品文件格式前的四步检查与可移植性测试

docs/portability.md 把前述原则翻译成了可执行的新功能开发守则。在新增任何产品自有文件格式或目录之前，先检查：是否已有既定的 Agent、编辑器或操作系统标准能表达同样的数据？如果确认仍需要产品私有格式，则必须满足四条要求：

1. 尽量使用明文、有文档的数据（plain, documented data）；
2. 把边界收窄（keep the boundary narrow），私有格式只覆盖真正必要的最小范围；
3. 为用户撰写的数据提供迁移或导出路径；
4. 避免让产品私有拷贝成为唯一可用的数据源（不要把共享标准数据复制一份私有版本当作唯一事实来源）。

最后，文档给出了一个可移植性特性的简单检验标准——判断一个功能是否可移植，就看三点：

• 用户能否清楚知道自己的数据存放在哪里；
• 其中标准化部分能否被另一个兼容工具直接复用；
• 用户离开 Open Interpreter 时，能否不丢失自己撰写的成果。

从仓库结构也能印证这套约束的执行痕迹：项目将用户可移植资产（AGENTS.md、.agents/skills）与运行时产物（日志迁移 SQL 见 codex-rs/state 下的 logs_migrations、memory_migrations 等目录）分置在不同体系，前者遵循开放约定、后者留在私有迁移管线内，正是"用户资产可移植、运行时状态可演进"的具体落点。

小结：把"用户的数据"还给用户

docs/portability.md 值得反复体会的核心，是一种克制：Open Interpreter 并没有因为自身是完整产品，就顺理成章地把指令、技能、配置统统收编为私有格式。它选择在存在通用标准的地方拥抱标准（AGENTS.md、.agents/skills/、MCP、ACP、exec 协议），在尚无通用标准的地方诚实保留私有状态并给出迁移路径，用可读性、就地读取、兼容读取器和导出能力四件套来兑现"不锁定用户"。对开发者而言，这套文档既是产品方向宣言，也是新功能评审时的实用 check-list——在往仓库里新增任何一种新的文件格式或目录之前，先对照它问一句："这条数据，用户能看懂、能带走、能在别的工具里再用一次吗？"