如何用 VAEN 打包和分享 AI 编码 Agent 的完整配置？

如果你和团队在用 AI 编码工具（Codex、Claude Code、Copilot），一定遇到过这个问题：精心调试好的 Agent 配置——指令文件、Skill 集合、MCP 服务声明——怎么才能干净地分享给同事或迁移到另一个项目？

以前的办法无非是复制粘贴指令，发 Slack 消息说”把这段加到你的 CLAUDE.md”，或者 zip 打包整个 .claude/skills/ 目录让对方手动解压。这种流程既容易漏东西，也说不清楚哪些环境变量需要对方自己配。

VAEN 是一个开源 CLI 工具，专门解决这个问题。它把 AI 编码 Agent 的配置打包成标准的 .agent 文件，同事拿到后一条命令就能完整导入。

VAEN 的核心理念

VAEN 不是运行时环境打包工具——它只打包配置和创作文件。具体来说，一个 .agent 包可以包含：

• 主指令和附加指令（Instructions）
• Skill 目录及其文件
• MCP 服务声明（仅配置，不含凭据）
• 元数据（版本、发布者、需要的环境变量名）

VAEN 从不打包凭据值、.env 文件、私钥、OAuth 状态或 MCP 服务实现代码。所有敏感信息通过变量名声明，由接收者在本地提供。

为什么不用普通的 Zip？

这是个很自然的疑问。Zip 确实能移动文件，但它回答不了几个关键问题：这个设置是干什么的？哪些文件应该导入到哪里？接收者需要提供哪些环境变量？

VAEN 通过 agent.yaml 清单文件让交接变得明确：

version: "0.1"
publisher: "Your Name"

instructions:
  main: "./AGENTS.md"
  includes:
    - "./coding-style.md"

artifacts:
  - type: skills
    path: "./skills/code-review"

requiredVars:
  - OPENAI_API_KEY

mcp:
  servers:
    - name: context7
      transport: stdio
      command: npx
      args: ["-y", "@upstash/context7-mcp"]
      env_vars:
        - CONTEXT7_API_KEY

每条信息都有明确的语义：instructions.main 是主指令文件，artifacts 是要打包的技能，requiredVars 明确告诉接收者需要设置哪些环境变量。

快速上手

安装

pipx install git+https://github.com/sjhalani7/vaen.git

或者本地安装：

git clone https://github.com/sjhalani7/vaen.git
cd vaen
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

创建最小化的 Agent 包

mkdir my-agent
cd my-agent
printf "# Agent Instructions\n\nUse concise, direct answers.\n" > AGENTS.md

创建 agent.yaml：

version: "0.1"
publisher: "Your Name"

instructions:
  main: "./AGENTS.md"

artifacts: []

验证并构建：

vaen validate -f agent.yaml
vaen build -f agent.yaml -o my-agent.agent

在另一个项目中导入

mkdir ../target-repo
cd ../target-repo
vaen import ../my-agent/my-agent.agent
vaen doctor

导入后的目录结构：

target-repo/
├── AGENTS.md
├── CLAUDE.md
├── .agent/
│   └── my-agent/
│       ├── instructions/
│       └── vaen/metadata.json
└── .claude/
    └── skills/

vaen doctor 会检查导入后的结构是否完整，但不会读取凭据值——这是一个很好的安全设计：它只验证”该有的文件都在”，不碰敏感数据。

实用场景

场景一：团队内共享最佳实践

让团队中的高级开发者维护一份 agent.yaml，包含统一的编码规范和 Skill 集合。新成员入职时只需要：

vaen import team-setup.agent --client codex
vaen doctor --client codex

场景二：跨项目复用配置

如果你维护多个项目，每个项目需要不同的 Agent 行为（比如一个偏前端、一个偏后端），可以为每个项目创建独立的 .agent 包，按需导入。

场景三：分享社区定义的 Skill 包

VAEN 仓库的 dist/agents/ 目录已经预置了几个社区包，包括 mattpocock 的 Skill 集合。你可以直接导入使用：

vaen import dist/agents/mattpocock-skills.agent

高级技巧：MCP 配置的跨客户端兼容

VAEN 的 MCP 声明是宿主中立的——你在 agent.yaml 里写 MCP 配置时不需要关心目标客户端。导入时 VAEN 会根据 --client 参数自动转换为对应的格式：

mcp:
  servers:
    - name: docs
      transport: http
      url: https://example.com/mcp
      bearer_token_env_var: DOCS_MCP_TOKEN

支持 codex、claude-code 和 copilot 三种客户端的格式写入。

注意事项

• 凭据安全：requiredVars 只存储变量名，不能写 NAME=value 或任何凭据值。接收者需要自己在本地设置对应的环境变量。
• 路径灵活性：agent.yaml 中的源路径可以指向仓库内部或外部（如 ~/.codex/AGENTS.md），但导入目标路径取决于客户端。
• 版本管理：version 字段目前是 "0.1"，主要用于未来兼容性。建议在 agent.yaml 中记录变更日志。

总结

VAEN 解决了 AI 编码 Agent 配置分享中一个真实且普遍存在的痛点。它用清晰的清单文件（agent.yaml）、标准化打包格式（.agent）和安全的凭据声明机制，让团队间的 Agent 配置交接从”复制粘贴 + 口头说明”升级为”一条命令搞定”。

对于正在逐步标准化 AI 编码工作流的团队来说，VAEN 是一个值得引入的工具——它本身解决的就是标准化过程中最头疼的”分发的最后一公里”问题。