# AgentENV

**Repository Path**: skillhub/agent-env

## Basic Information

- **Project Name**: AgentENV
- **Description**: `agentenv` 是一个本地 AI 环境管理工具，目标是把团队成员本机已经跑通的 AI IDE 配置提取为项目内的源码真相，并以 `.agentenv/` 目录的形式提交到 Git，供其他 IDE 或 Agent 在本地复用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Agent, skills, MCP, ai-ide

## README

# agentenv

`agentenv` 是一个本地 AI 环境管理工具，目标是把团队成员本机已经跑通的 AI IDE 配置提取为项目内的源码真相，并以 `.agentenv/` 目录的形式提交到 Git，供其他 IDE 或 Agent 在本地复用。

## 相比较Skills框架的优势

1.支持更多功能，如Rules、MCP、Skills等
2.原样提取，不做脱敏，不做 API Key 清洗，不做 AST 分析
3.支持更多主流 IDE，如Cursor、Trae、Trae-CN、OpenCode等，即将支持CodeX / Windsurf / Claude Code等

当前仓库处于第一阶段实现，重点已经落在以下三件事上：

- 建立 `core/`、`cli/`、`gui/` 三层隔离的大仓结构
- 打通 Cursor、Trae、Trae-CN、OpenCode 的 `pack/apply/clone` 主链路
- 明确安全边界、路径基准化和 `manifest.json` 版本迁移机制

## 设计原则

- 原样提取：不做脱敏，不做 API Key 清洗，不做 AST 分析
- 唯一路径例外：仅在 MCP 的 `command/args` 中，对位于当前项目根目录内的绝对路径做相对化
- 强阻断安全：`pack` 完成后必须阻断用户继续操作，直到其明确确认明文风险
- 三层架构：`cli/` 和 `gui/` 不直接操作文件，文件读写统一经由 `core/`
- 做减法：先保证标准结构、兼容路径和数据可逆，再扩更多 IDE

## 当前能力

当前已实现：

- CLI 命令：
  - `agentenv pack`
  - `agentenv apply --target <ide>`
  - `agentenv clone <url> --target <ide>`
- GUI：
  - Wails v2 可运行桌面入口
  - 项目列表与最近项目继续打开
  - 项目列表进入时锁定根目录
  - 点击“应用到 IDE”后在弹窗中选择目标 IDE
  - 自动识别当前项目 IDE
  - `pack` 后返回阻断态结果
  - 前端红色安全模态，必须勾选确认后才能关闭
- IDE 适配：
  - `CursorExtractor`
  - `CursorInjector`
  - `TraeExtractor`
  - `TraeInjector`
  - `TraeCNExtractor`
  - `TraeCNInjector`
  - `OpenCodeExtractor`
  - `OpenCodeInjector`
- 标准能力：
  - Rules 合并提取
  - Skills 递归扫描、写入与回放
  - MCP 标准化
  - 项目内绝对路径相对化与反向恢复
  - `manifest.json` 版本迁移与版本不一致提醒

当前未实现：

- Windsurf / Claude Code 的提取与注入
- GUI 内核热更新
- 社区包签名、校验、索引
- 更细粒度的 Rules 反向拆分回原 IDE 多文件结构

## 标准目录

`pack` 成功后会生成以下目录：

```text
.agentenv/
├── manifest.json
├── brains/
│   ├── rules.md
│   └── skills/
└── hands/
    └── mcps.json
```

说明：

- `manifest.json`：记录标准版本、来源 IDE、提取时间、项目根 token 信息
- `brains/rules.md`：合并后的规则文本
- `brains/skills/`：原样提取的 skill 文件树
- `hands/mcps.json`：统一后的 MCP 声明

## 当前架构

```text
cmd/
└── agentenv/          # CLI 程序入口
cli/                   # Cobra 命令定义、参数接收、终端输出
core/                  # 业务核心层
├── contracts/         # 抽象接口
├── entity/            # 标准模型与版本常量
├── extractor/         # IDE -> .agentenv
├── injector/          # .agentenv -> IDE
├── normalize/         # 项目内路径相对化与恢复
├── service/           # pack / apply / clone 编排
└── storage/           # 文件系统实现
gui/                   # GUI 适配层
├── backend/           # Wails 可调用后端，转调 core
└── frontend/          # 内嵌前端静态资源
main.go                # Wails GUI 入口
app.go                 # Wails 应用包装层
```

补充：

- 根目录 `frontend/wailsjs/` 是 Wails 生成的前后端绑定代码，不作为主架构分层的一部分单独展开

### 分层职责

- `core/`
  - 唯一允许编排业务和文件抽象的层
  - 负责标准数据结构、提取器、注入器、路径处理与 pack/apply/clone 服务编排
- `cli/`
  - 负责 Cobra 命令定义、提示文本、安全阻断交互
  - 不应自行读写 `.agentenv/` 或 IDE 配置
- `gui/`
  - `backend/` 暴露 Wails 可调用接口
  - `frontend/` 只承载视图和用户交互
  - 不应复制 `core` 逻辑

## 核心数据模型

### Manifest

当前 `manifest.json` 版本为 `2`。

关键字段：

- `version`
- `sourceIde`
- `extractedAt`
- `projectRootToken`
- `originalProjectRoot`

其中：

- `projectRootToken` 当前固定为 `$PROJECT_ROOT`
- `originalProjectRoot` 保留提取时的绝对根目录，仅用于上下文记录，不参与脱敏

### Standard MCP

MCP 标准模型包含：

- `version`
- `servers[]`

每个 `server` 关键字段：

- `name`
- `transport`
- `command`
- `args`
- `env`
- `extra`
- `sourceIde`
- `disabled`

其中 `command` 和 `args` 使用 `NormalizedValue` 表达是否为项目相对路径。

## 路径基准化策略

只处理两类位置：

- MCP `command`
- MCP `args`

规则：

- 如果值不是绝对路径，则保持原样
- 如果值是绝对路径，但不在当前项目根目录下，则保持原样
- 如果值是绝对路径，且位于当前项目根目录下，则转为相对路径并标记 `projectRelative=true`
- `apply` 时仅对 `projectRelative=true` 的值做恢复

这保证了：

- 项目内路径跨设备可迁移
- 项目外路径不被误改写
- 标准结构可逆

## Rules 与 Skills 策略

### Rules

当前 Cursor 提取会合并以下来源：

- `.cursorrules`
- `AGENTS.md`
- `.cursor/rules/*.md`

合并结果统一写入 `.agentenv/brains/rules.md`。

当前 Cursor 回放阶段会把合并后的规则整体写回 `.cursorrules`。这是一种“先保证稳定、再谈精细拆分”的策略。

### Skills

当前 Cursor 提取会递归扫描：

- `.cursor/skills/**`

扫描结果按相对目录结构原样写入：

- `.agentenv/brains/skills/**`

`apply` 时会先清空目标 `.cursor/skills/`，再按 bundle 中的相对路径完整重建，避免切分支后遗留旧文件。

## Manifest 版本迁移

当前策略：

- 读取到 `v2`：直接使用，必要时补默认字段
- 读取到 `v1`：在内存中迁移为 `v2`，并返回 warning，提示用户可能切换了分支或本地二进制未更新，建议重新 `pack`
- 读取到高于当前程序支持的版本：直接报错阻断，避免老版本程序误解释新结构

这意味着：

- 旧包可以尽量兼容使用
- 新包不会被旧程序静默损坏

## 安全阻断

### CLI

`pack` 完成后：

- 触发系统通知
- 打印红色多行警告块
- 要求用户输入 `I UNDERSTAND THE RISK`

如果输入不完全一致，命令直接报错退出。

### GUI

GUI `pack` 返回 `blocked` 状态，并附带 `securityBlock` 结构。

前端：

- 弹出不可绕过的模态
- 必须勾选“我已知晓包含明文密钥，绝不外传”
- 勾选前关闭按钮保持禁用

## Clone 行为

`clone` 目前的设计是：

- 下载 zip 包
- 解压到本地 `.agentenv/`
- 自动调用 `apply`

本地不做额外审核、脱敏或结构校验。这个行为是刻意的，因为假设社区包已在云端完成人工审核。

## 运行方式

### 环境要求

- Go `1.22+`
- Windows / Linux / macOS

### 常用命令

```bash
go mod tidy
go test ./...
go build ./...
```

CLI:

```bash
go run ./cmd/agentenv pack
go run ./cmd/agentenv apply --target cursor
go run ./cmd/agentenv clone https://example.com/reviewed.zip --target cursor
```

GUI:

```bash
wails dev
```

Make:

```bash
make build
make gui-build
make gui-run
make release
```

说明：

- GUI 开发运行以 `wails dev` 为准，Wails CLI 会从仓库根目录读取 `main.go` 和 `wails.json`
- GUI 打包以 `wails build` 为准，不再使用 `go run ./cmd/agentenv-gui`
- 当前在 Windows 上使用 `Wails CLI v2.10.2` 时，需要保持 `github.com/wailsapp/go-webview2 v1.0.21`

## 跨平台构建

`make release` 当前输出 CLI 二进制，目标平台为：

- `windows/amd64`
- `windows/386`
- `linux/amd64`
- `linux/arm64`
- `darwin/amd64`
- `darwin/arm64`

说明：

- 当前 `release` 只覆盖 CLI
- GUI 目前提供本机构建入口，不做完整 GUI 跨平台发行编排

## 测试现状

当前已有测试覆盖：

- 项目内路径相对化 / 恢复
- Cursor MCP 提取
- Skills 提取
- 旧版 `manifest` 迁移
- 新版 `manifest` 阻断

建议新增的测试方向：

- `clone` 对不同 zip 根目录布局的处理
- `CursorInjector` 对 skills/rules 的回放结果
- GUI backend DTO 的契约稳定性

## 当前开发边界

在进入多 IDE 扩展前，需要继续维持以下边界：

- 不要在 `cli/` 或 `gui/` 中复制 `core` 逻辑
- 不要把“原样提取”扩展成隐式脱敏
- 不要把项目外绝对路径误改成相对路径
- 不要把尚未完成的多 IDE 能力写进用户文案

## 下一步建议

- 扩展 Windsurf / Claude Code 的提取与注入
- 抽象 Rules 的来源与回放策略
- 为 GUI 增加更完整的结果面板与 warning 展示
- 为 `clone`、`injector` 和 GUI 增加更细粒度测试