为什么需要 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 创建任务 | | run-task | 当所选客户端能提供已验证的 actual model/effort 证据时，用 fresh 隔离 executor/reviewer 续跑生命周期；Codex 现已具备实验性的 Hooks + App Server 证据通道，但在该通道接入 delegation receipt 前仍不会启用 orchestration | | analyze-task | 明确范围与风险，再选择精简、标准或完整路径 | | review-analysis | 仅在完整路径需要独立需求检查点时审查分析 | | plan-task / review-plan | 标准和完整路径需要设计方案；只有完整路径独立审查方案 | | code-task → review-code | 实现并测试；code-task 创建本地 checkpoint，再由结构化审查检视该 checkpoint | | create-pr → complete-task | 将已通过审查的 checkpoint 发布到任务绑定目标分支，并在合并和最终门禁通过后归档 |

启动时可提供原子角色策略，例如：$run-task --task 42 --executor-model <id> --executor-reasoning-effort <值> --reviewer-model <id> --reviewer-reasoning-effort <值>。两个角色可以使用同一模型。完全没有显式策略时，run-task 读取当前 Agent Client 可选的 agentClients[].orchestration；两个来源都不完整时，会在创建任何 run 前展示宿主模型选择指引。重入使用已持久化的 run 策略。升级 agent-infra 前必须完成或清空 active run；不受支持的磁盘状态会失败关闭且不改写。

完整清单（任务状态、发布、安全、项目维护等 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。

许可协议

MIT

社区

• 微信公众号：FitFramework
• QQ 技术交流群：1029802553