AgentX CLI

English | 中文

将一份声明式 Manifest 编译为多个 AI Agent 的可复现开发环境。

本仓库是 AgentX 的本地环境管理 CLI。它负责 Manifest、Lockfile、Skills、Rules、MCP 配置、Registry 登录，以及设备同步和回滚。

快速开始

cargo run -- init
cargo run -- lock
cargo run -- install --yes --frozen
cargo run -- diff

团队同步和设备闭环：

agentx registry login https://registry.example.com --token "$AGENTX_TOKEN" --workspace "$AGENTX_WORKSPACE_ID"
agentx team pull --output agentx.yaml
agentx agent plan --device "$AGENTX_DEVICE_ID"
agentx agent sync --device "$AGENTX_DEVICE_ID"

完整产品说明见 PRODUCT.md。组织主页、贡献指南和安全政策见 AgentX GitHub Organization。

声明式管理 Codex、Claude Code、Cursor、Windsurf、Gemini CLI、GitHub Copilot、Cline 和 Grok Build 的 Skills 与工作环境。

当前状态

Rust CLI 已实现本地 Skill 生命周期、八类 Agent 的 Rules 和 MCP 配置适配，以及 Registry login、publish、pull；通过 --workspace 使用 workspace scoped Registry，team pull/team push 可同步 workspace 团队 manifest。Go API 提供 workspace/membership、策略执行、版本化 manifest、Registry、审计、Drift、设备 heartbeat、cursor 分页和 scoped artifact 下载；Vue 3 控制台支持 workspace、成员角色、manifest、策略、Registry、设备、Drift 和 Audit 操作。

cd cli
cargo run -- init
cargo run -- doctor
cargo run -- install --yes
cargo run -- diff

安装到指定 Agent 时使用 --target：

agentx install --target cursor --yes --frozen
agentx install --target gemini --yes --frozen
agentx install --target cline --yes --frozen
agentx install --target grok --yes --frozen

省略 --target 时保持向后兼容，只安装 Codex 和 Claude Code。agentx diff --target grok 可单独检查某个 Agent。

支持的 target 和生成位置：

Target	Rules	Skills	MCP
codex	AGENTS.md	~/.codex/skills	~/.codex/config.toml
claude	CLAUDE.md (managed block)	~/.claude/skills	.mcp.json
cursor	.cursor/rules/agentx.mdc	.cursor/skills	.cursor/mcp.json
windsurf	.windsurf/rules/agentx.md	.windsurf/skills	~/.codeium/windsurf/mcp_config.json
gemini	GEMINI.md	.gemini/skills	.gemini/settings.json
copilot	.github/copilot-instructions.md	.github/skills	~/.copilot/mcp-config.json
cline	.clinerules/agentx.md	.cline/skills	~/.cline/mcp.json
grok	.grok/rules/agentx.md	.grok/skills	.grok/config.toml ([mcp_servers.<name>])

交互式安装会先显示每个 Skill 和 Rules 的目标位置，以及 MCP 的命令、完整参数、检测到的环境变量引用和配置路径。Skill 安全扫描会拒绝符号链接、超过 2 MiB 的文件、凭据/私钥文件名，以及原生或非预期可执行文件。Git Skill source 必须提供固定 ref。

推送形如 v0.1.2 的 Tag 会触发 .github/workflows/release.yml，先运行格式检查、测试和 release 构建，再创建 GitHub Release 并上传 Linux CLI 压缩包和 SHA-256 校验和。Tag 可通过 GitHub Actions 的 Tag workflow 从指定分支创建。

当前 Manifest 的 MCP 字段只支持 command 和 args；URL、headers、env 等传输能力不会被 CLI 自动生成，需要在 Agent 原生配置中维护。

CLI 远程凭据保存在用户配置目录，拉取时会重新校验 SHA-256。服务端可使用 PostgreSQL、API token、HMAC JWT 或配置 AGENTX_OIDC_ISSUER 启用 OIDC discovery/JWKS 验证，并支持 Ed25519 artifact 签名验证。

服务端

cd server
AGENTX_DATA_DIR=../data go run ./cmd/app

Registry API 文档见 agentx-server/openapi.yaml，本地部署和服务端实现见 agentx-server。开源贡献规则见 CONTRIBUTING.md，安全问题见 SECURITY.md。

可选依赖使用本机已有镜像启动：docker compose --profile cache up -d，或 docker compose --profile object-store up -d。默认 API 不依赖 Redis/MinIO。

Hosted artifact storage 可通过 AGENTX_ARTIFACT_STORE=s3 启用 S3/MinIO 适配器，并设置 AGENTX_S3_ENDPOINT、AGENTX_S3_ACCESS_KEY、AGENTX_S3_SECRET_KEY、AGENTX_S3_BUCKET 和可选的 AGENTX_S3_SECURE=true。发布、workspace、策略、manifest、设备和成员变更会写入 outbox，由内置 worker 重试处理。

策略文档可使用 {"require_signature":true} 强制签名，或使用 {"require_approval":true} 将新版本置为 pending_approval；审批前 workspace 下载会被拒绝。

Hosted Registry 使用前先执行 server/migrations/001_initial.sql。常用远程命令：

agentx registry login https://registry.example --token "$AGENTX_TOKEN"
agentx registry login https://registry.example --token "$AGENTX_TOKEN" --workspace "$AGENTX_WORKSPACE_ID"
agentx registry publish my-skill 1.2.3 ./my-skill.tar --signature "$SIGNATURE"
agentx registry pull my-skill 1.2.3 --output ./my-skill.tar
agentx team pull --output agentx.yaml
agentx team push --input agentx.yaml

设备闭环命令会从 workspace manifest 生成计划，下载并校验 artifact，写入本地设备缓存，再用 heartbeat 上报实际状态；每次同步会保存上一状态，可执行回滚：

agentx agent plan --device laptop-2
agentx agent sync --device laptop-2
agentx agent rollback --device laptop-2

生产前可用 staging compose 启动 PostgreSQL、MinIO、Dex OIDC、API 和控制台，并运行验收脚本。脚本要求一个通过 OIDC 登录得到的 bearer token 和 workspace ID：

docker compose -f docker-compose.staging.yml up -d --build
AGENTX_TOKEN=... AGENTX_WORKSPACE_ID=... ./scripts/staging-acceptance.sh
AGENTX_DATABASE_URL='postgres://agentx:agentx-staging@localhost:5433/agentx' ./scripts/backup-restore.sh backup
./scripts/staging-key-rotation.sh

服务提供 /readyz、/metrics，outbox 事件超过最大重试次数会进入 dead-letter 并记录最后错误；AGENTX_RATE_LIMIT_PER_MINUTE 可调整 API 限流。