Agent Infra
AI 编程代理的协作基础设施 —— 为 Claude Code、Codex、Antigravity CLI、OpenCode 提供 skills、工作流和沙箱。
从 Issue 到合并 PR，由风险选择相称的生命周期。 每个任务都先分析，每份实现都接受独立代码审查。
English · 中文
为什么需要 agent-infra？
越来越多的团队会在同一个仓库里混用 Claude Code、Codex、Antigravity CLI、OpenCode 等 AI TUI，但每个工具往往都会带来自己的命令体系、提示词习惯和本地约定。缺少共享层时，结果通常是工作流割裂、初始化重复、任务历史难以追踪。
agent-infra 的目标就是把这层共享基础设施标准化。它为所有支持的 AI TUI 提供统一的任务生命周期、统一的 skill 词汇、统一的项目治理文件、隔离的开发沙箱以及统一的升级路径，让团队切换工具时不必重新发明流程。
实战演示
演示动画通过 Git LFS 存储。克隆前请安装 Git LFS 并运行
git lfs install； 已有检出可运行git lfs pull。如果图片变成很小的文本指针或缺失，请先用git lfs ls-files核对跟踪状态，再重试git lfs pull。
完成初始化后，在你的 AI TUI 中打开项目并安装最新 skills：
/update-agent-infra
AI 读取
.agents/.airc.json，自动定位已安装的模板根目录，并通过sync-templates.js确定性地同步最新的 skill 清单、managed 文件和注册表。
场景：Issue #42 报告 "登录接口在邮箱包含加号时返回 500"。每个任务都从分析开始，并由分析根据可观察事实记录一条规范路径：
| 路径 | 阶段 | 适用条件 |
|---|---|---|
| 精简路径 | analyze → code → review-code | 范围和验收明确，不需要独立设计或文档审计决策 |
| 标准路径 | analyze → plan → code → review-code | 实现需要明确跨模块契约、数据流或测试策略 |
| 完整路径 | analyze → review-analysis → plan → review-plan → code → review-code | 存在具体的验收争议、高代价接口/schema/迁移选择，或真实外部/安全边界，需要独立审查 |
文件数量、模块数量或可能存在的风险不能单独触发完整路径。后续 finding 只有在新证据成立时才会把工作返回分析、方案或实现阶段；每条路径都保留独立 review-code。
假设分析认为应用层边界需要明确方案，因此选择标准路径：
/import-issue 42 # AI 读取 Issue，创建任务，提取需求
/analyze-task --task <task-id> # AI 扫描代码库、记录所选路径，输出 analysis.md
/plan-task --task <task-id> # AI 提出修复方案
你审查方案后用自然语言回复：
方案方向没问题，但不要动数据库结构。
只在应用层的 LoginService 里修复就行。
AI 按你的要求重跑
/plan-task更新方案并确认。
/code-task --task <task-id> # AI 编写修复代码、测试，并创建本地 checkpoint commit
/review-code --task <task-id> # fresh 隔离 reviewer 报告一个次要问题
/code-task --task <task-id> # AI 修复次要问题、重新验证，并创建新的 checkpoint
/review-code --task <task-id> # reviewer 审查并通过当前 checkpoint
/create-pr --task <task-id> # 将已审查分支发布到任务绑定目标分支；PR 自动关联 Issue #42
/complete-task --task <task-id> # 任务归档
一条由分析选择的路径、一次自然语言纠正和一次独立代码审查。 生命周期会让证据与审查深度和任务风险相称。
以上每条命令在 Claude Code、Codex、Antigravity CLI、OpenCode 中完全通用。任务进行到一半切换工具，工作流状态照常延续。每个 skill 背后做了什么，见 内置 AI Skills。
核心特性
- 多 AI 协作：为 Claude Code、Codex、Antigravity CLI、OpenCode 提供统一的协作模型
- 引导 CLI + skill 驱动执行：初始化一次，后续日常操作交给 AI skills
- IM 命令桥接：把飞书消息路由到内置命令、任务只读视图、沙箱管理和受控生命周期 skill 执行
- 双语文档：英文为主文档，配套同步的中文版本
- 模板源架构：
templates/目录镜像最终渲染出的项目结构 - AI 辅助升级：模板升级时可合并变更，同时尽量保留项目侧定制
- 可审计的过程数据归档：把本地任务与 GitHub 证据保存为只追加、可校验的快照
沙箱控制边界
direct-host 生命周期和工作流命令在当前 CLI 进程中执行。任务沙箱把请求发送给所属 broker；broker 会先校验请求、manifest、generation、owner、lease 和 controller，再启动一次性 executor。系统不再使用宿主 socket、worker token 或用户级 task-control 服务。
任务沙箱内的 task 目录只允许其绑定任务读写。产物命令只接受类型化 workflow 操作和规范的产物 basename。executor 使用 O_NOFOLLOW 打开候选文件，通过同一个文件描述符读取并计算摘要，检查可观察的元数据变化，再把已校验字节原子落入权威 task 目录。
快速开始
1. 安装 agent-infra
方式 A - npm（推荐）
npm install -g @fitlab-ai/agent-infra
方式 B - Shell 脚本
# 便捷封装：检测 Node.js 后，内部执行 npm install -g
curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh
方式 C - Homebrew (macOS)
# 新版 Homebrew 默认拒绝加载第三方 tap 的 formula，
# 会导致升级被静默跳过。首次安装前先信任本 tap。
brew trust fitlab-ai/tap
brew install fitlab-ai/tap/agent-infra
更新 agent-infra
ai update
ai update 用于更新已安装的 agent-infra CLI。在已初始化项目中，使用
ai sync 刷新项目 seed files 和文件注册表。
对应的包管理器命令仍然是：
npm update -g @fitlab-ai/agent-infra
# 或者通过 Homebrew 安装时：
brew upgrade agent-infra
查看当前版本：
ai version
# 或：agent-infra version
2. 初始化新项目
cd my-project
ai init
# 或：agent-infra init
CLI 会收集项目元数据，让你选择启用的 Agent Client，安装该客户端需要的 update-agent-infra 种子命令，并生成 .agents/.airc.json。
ai是agent-infra的简写命令，两者等价。
3. 渲染完整基础设施
在任意 AI TUI 中执行 update-agent-infra：
| TUI | 命令 |
|---|---|
| Claude Code | /update-agent-infra |
| Codex | $update-agent-infra |
| Antigravity CLI | /update-agent-infra |
| OpenCode | /update-agent-infra |
| TraeCode CLI | /update-agent-infra |
该命令会检测当前打包模板版本并渲染所有受管理文件。首次安装和后续升级都使用同一条命令。
核心命令
以下命令用于独立管理五个内建 Agent Client：
ai agent-client list
ai agent-client status
ai agent-client enable codex
ai agent-client disable antigravity-cli
ai agent-client configure
最常用的生命周期命令，按交付顺序排列。命令前缀因 TUI 而异（Claude Code/Antigravity/OpenCode/TraeCode 用 /skill，Codex 用 $skill），工作流语义保持一致。
| 命令 | 用途 |
|---|---|
create-task / import-issue | 从描述或 GitHub Issue 创建任务 |
analyze-task | 明确范围与风险，再选择精简、标准或完整路径 |
review-analysis | 仅在完整路径需要独立需求检查点时审查分析 |
plan-task / review-plan | 标准和完整路径需要设计方案；只有完整路径独立审查方案 |
code-task → review-code | 实现并测试；code-task 创建本地 checkpoint，再由结构化审查检视该 checkpoint |
create-pr → complete-task | 将已通过审查的 checkpoint 发布到任务绑定目标分支，并在合并和最终门禁通过后归档 |
完整清单（任务状态、发布、安全、项目维护等 skill）见 内置 AI Skills。
安装效果
安装完成后，项目将获得完整的 AI 协作基础设施：
my-project/
├── .agents/ # 共享 AI 协作配置
│ ├── .airc.json # 中央配置文件
│ ├── workspace/ # 任务工作区（git 忽略）
│ ├── skills/ # 内置 AI skills
│ ├── workflows/ # 4 个预置工作流
│ └── templates/ # 任务与产物模板
├── .claude/ # Claude Code 配置与命令
├── .opencode/ # OpenCode 配置与命令
└── AGENTS.md # 通用 AI agent 指令
文档
深度指南位于 docs/zh-CN/：
- 过程数据归档 — 采集、校验、审计、修复、导出、隐私与备份指南
- 架构概览 — 引导 CLI、端到端流程、分层架构
- 平台支持 — macOS、Linux、Windows；沙箱引擎与资源配置
- 沙箱 — 沙箱 aliases、宿主-沙箱文件交换、用户级 dotfiles 通道
- Benchmark 契约与威胁模型 — 版本化 benchmark schema、信任边界与安全保证
- 飞书桥接 — 配置飞书长连接 adapter、命令路由、权限和 TUI 选择
- 内置 AI Skills — 按使用场景分组的完整 skill 清单
- 自定义 Skills — 创建并同步项目专属 skill
- 自定义工具调用 — 配置自定义工具的下一步命令
- 预置工作流 — 分阶段交付链路与示例流程
- 配置参考 —
.agents/.airc.json、外部源、版本管理 - 文件管理策略 — managed / merged / ejected 更新策略
参与贡献
开发规范请参阅 CONTRIBUTING.zh-CN.md。
许可协议
社区
- 微信公众号：
FitFramework - QQ 技术交流群：
1029802553
