声明式，不拼凑#

AgentEnv 的核心是 agent.yaml —— 一个声明式的环境定义文件：

name: my-ai-env
description: "我的 AI 开发环境"

skills:
  code-reviewer:
    source: github:myorg/code-review-skill
    version: ">=0.5"

mcps:
  filesystem:
    source: npm:@modelcontextprotocol/server-filesystem
    version: "0.6.0"
    config:
      root: /home/user/projects

你只需要声明想要什么，AgentEnv 负责找到、下载、安装、激活。这跟 package.json + npm install 的思路一脉相承，但适配的是 AI 编码工具的生态。

可重现，版本锁定#

声明之后执行 agentenv lock，它会跑一个 PubGrub CDCL 解析器——就是 Dart/Flutter 用那个算法——来求解依赖图：

• 自动发现传递依赖（skill A 依赖 skill B，B 又依赖 C）
• 处理语义化版本约束（^1.0、>=2.0、~3.5.1）
• 检测冲突并给出精确的冲突报告

error: conflict detected
  code-reviewer@>=1.0 requires lint-helper@^2.0
  my-other-skill@>=0.5 requires lint-helper@^1.0
  lint-helper@^2.0 and lint-helper@^1.0 are incompatible

解析完成后生成 agent.lock，包含每个包的 SHA-256 校验、解析版本、来源——这是你在另一台机器上得到完全相同环境的保证。

六种源，不分来源#

AgentEnv 支持 6 种包来源协议：

也就是说，你可以把一个 GitHub 上的 skill、一个 npm 上的 MCP 服务器、一个本地开发中的 hook 脚本，扔进同一个环境管理。这对「正在开发 skill 同时又在用别人的 MCP」这种常见场景极其友好。

六种包，各司其职#

AgentEnv 中，「包」（package）是一个抽象概念，覆盖了 AI 智能体生态中所有需要版本管理和环境隔离的东西。目前支持六种包类型：

每种包在 agent.yaml 中的声明格式完全一致，只需要三个字段：

# 必填：source —— 从哪里获取这个包
source: github:owner/repo

# 可选：version —— 语义化版本约束（默认 *，即任意版本）
version: ">=0.5"

# 可选：config —— 包专属的配置项，由包的消费者自行解读
config:
  root: /home/user/projects

一个包含所有六种类型的完整 agent.yaml 长这样：

name: my-ai-env
description: "我的全栈 AI 开发环境"

# 技能（skill）：可复用的智能体能力模块
skills:
  code-reviewer:
    source: github:myorg/code-review-skill
    version: ">=0.5"

# MCP 服务器：连接外部工具的桥梁
mcps:
  filesystem:
    source: npm:@modelcontextprotocol/server-filesystem
    version: "0.6.0"
    config:
      root: /home/user/projects

# 智能体（agent）：自定义 agent 的完整规格
agents:
  senior-dev:
    source: github:myorg/agents
    version: "~1.2"

# 工具（tool）：辅助工具和配置
tools:
  formatter:
    source: url:https://example.com/tools/formatter.tar.gz

# 钩子（hook）：生命周期事件触发脚本
hooks:
  pre-activate:
    source: file:/home/user/hooks/check-env.sh
  post-deactivate:
    source: local:./hooks/cleanup.sh

# 提示词（prompt）：可复用的提示词模板
prompts:
  code-review:
    source: git:https://github.com/myorg/prompts.git
    version: ">=2.0"

同一个环境可以混用任意类型的包，不限制种类和数量。同一个类型下包名必须唯一，但不同类型之间可以重名（比如可以同时有一个叫 code-reviewer 的 skill 和一个叫 code-reviewer 的 prompt）。

这种设计的妙处在于——不论是 GitHub 上的开源 skill、npm 上的 MCP 包、还是本地开发中的 hook 脚本，对 AgentEnv 来说都是「包」，都走同一套解析、下载、安装、激活的流水线。 你不用为不同种类的东西学不同的命令，也不用操心它们的存储路径和配置格式。

四个框架，一套流程#

不管你用的是 Claude Code、OpenCode、Cursor 还是 Codex，AgentEnv 的命令都一样：

agentenv create --agent opencode my-env
agentenv add skill code-reviewer --source github:myorg/reviewer
agentenv lock
agentenv install
agentenv activate my-env

框架切换只是一个 --agent 参数的区别。每个框架适配器知道自己的配置路径、格式（JSON、JSONC、TOML）、以及如何正确地读写而不破坏已有配置。

特别值得一提的是 OpenCode 适配器的 JSONC 支持：OpenCode 的配置文件是带注释的 JSON（JSONC），AgentEnv 用了 tailscale/hujson 来做注释保留的读写，不会像 encoding/json 那样把注释全部吃光。

事务性激活，不留下残局#

激活环境时，AgentEnv 做的不是简单「往配置文件里塞几行」：

备份（backup）→ 校验（validate）→ 应用（apply）→ 失败回滚（rollback）

如果校验失败或者任何步骤出错，它会自动恢复到变更前的状态。不会出现「配置改了一半 agent 跑不起来了」的情况。

内容寻址存储#

所有下载的包存在一个内容寻址的本地仓库里。两个环境都用到 lint-helper@1.2.0？只存一份。某个包不再被任何环境引用？垃圾回收可以清理。跨文件系统的话，symlink 降级为文件复制。