# @fitlab-ai/agent-infra 中文文档

规范地址：https://npmcn.com/package/%40fitlab-ai/agent-infra/

版本：0\.12\.4
npm 元数据更新时间：2026-11-13T05:22:02.064Z
中文译文更新时间：2026-11-14T20:53:15.584Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fitlab-ai/agent-infra
原文对照：https://npmcn.com/package/%40fitlab-ai/agent-infra/?lang=original
项目主页：https://github.com/fitlab-ai/agent-infra#readme
源码仓库：https://github.com/fitlab-ai/agent-infra

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：7.4 MB，1082 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.9\.0
- 运行依赖：8 个
- 首次发布：2026-03-18T08:46:53.387Z
- 最新版本发布：2026-11-13T05:22:01.671Z
- 近 30 天下载量：2395（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 79 个）

## 中文简介

AI多工具协作基础设施的启动工具——与克洛德码,Codex,Antigravity CLI和OpenCode合作

## 安装

```sh
npm install @fitlab-ai/agent-infra
```

也可以使用：`pnpm add @fitlab-ai/agent-infra`、`yarn add @fitlab-ai/agent-infra`、`bun add @fitlab-ai/agent-infra`

## README

![Agent Infra 标志](https://npmcn.com/package/%40fitlab-ai/agent-infra/assets/logo.svg)

# Agent Infra

AI 编程代理的协作基础设施 —— 为 Claude Code、Codex、Antigravity CLI、OpenCode 提供 skills、工作流和沙箱。

**从 Issue 到合并 PR，由风险选择相称的生命周期。** 每个任务都先分析，每份实现都接受独立代码审查。

[![npm version](https://img.shields.io/npm/v/@fitlab-ai/agent-infra)](https://www.npmjs.com/package/@fitlab-ai/agent-infra) [![npm downloads](https://img.shields.io/npm/dm/@fitlab-ai/agent-infra)](https://www.npmjs.com/package/@fitlab-ai/agent-infra) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://npmcn.com/package/%40fitlab-ai/agent-infra/License.txt) [![Node.js >= 22.9.0](https://img.shields.io/badge/Node.js-%3E%3D22.9.0-brightgreen?logo=node.js)](https://nodejs.org/) [![GitHub release](https://img.shields.io/github/v/release/fitlab-ai/agent-infra)](https://github.com/fitlab-ai/agent-infra/releases) [![codecov](https://codecov.io/gh/fitlab-ai/agent-infra/graph/badge.svg)](https://codecov.io/gh/fitlab-ai/agent-infra) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://npmcn.com/package/%40fitlab-ai/agent-infra/CONTRIBUTING.zh-CN.md)

[English](https://npmcn.com/package/%40fitlab-ai/agent-infra/README.md) · **中文**

## 为什么需要 agent-infra？

越来越多的团队会在同一个仓库里混用 Claude Code、Codex、Antigravity CLI、OpenCode 等 AI TUI，但每个工具往往都会带来自己的命令体系、提示词习惯和本地约定。缺少共享层时，结果通常是工作流割裂、初始化重复、任务历史难以追踪。

agent-infra 的目标就是把这层共享基础设施标准化。它为所有支持的 AI TUI 提供统一的任务生命周期、统一的 skill 词汇、统一的项目治理文件、隔离的开发沙箱以及统一的升级路径，让团队切换工具时不必重新发明流程。

## 实战演示

![CLI 安装初始化演示](https://npmcn.com/package/%40fitlab-ai/agent-infra/assets/demo-init.gif)

> 演示动画通过 Git LFS 存储。克隆前请安装 Git LFS 并运行 `git lfs install`； 已有检出可运行 `git lfs pull`。如果图片变成很小的文本指针或缺失，请先用 `git lfs ls-files` 核对跟踪状态，再重试 `git lfs pull`。

完成初始化后，在你的 AI TUI 中打开项目并安装最新 skills：

```bash
/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`。

假设分析认为应用层边界需要明确方案，因此选择**标准路径**：

```bash
/import-issue 42           # AI 读取 Issue，创建任务，提取需求
/analyze-task --task <task-id>    # AI 扫描代码库、记录所选路径，输出 analysis.md
/plan-task --task <task-id>       # AI 提出修复方案
```

> **你审查方案后用自然语言回复：**

```
方案方向没问题，但不要动数据库结构。
只在应用层的 LoginService 里修复就行。
```

> AI 按你的要求重跑 `/plan-task` 更新方案并确认。

```bash
/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](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/skills.md)。

## 核心特性

-   **多 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（推荐）**

```bash
npm install -g @fitlab-ai/agent-infra
```

**方式 B - Shell 脚本**

```bash
# 便捷封装：检测 Node.js 后，内部执行 npm install -g
curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh
```

**方式 C - Homebrew (macOS)**

```bash
# 新版 Homebrew 默认拒绝加载第三方 tap 的 formula，
# 会导致升级被静默跳过。首次安装前先信任本 tap。
brew trust fitlab-ai/tap
brew install fitlab-ai/tap/agent-infra
```

### 更新 agent-infra

```bash
ai update
```

`ai update` 用于更新已安装的 agent-infra CLI。在已初始化项目中，使用 `ai sync` 刷新项目 seed files 和文件注册表。

对应的包管理器命令仍然是：

```bash
npm update -g @fitlab-ai/agent-infra
# 或者通过 Homebrew 安装时：
brew upgrade agent-infra
```

查看当前版本：

```bash
ai version
# 或：agent-infra version
```

### 2\. 初始化新项目

```bash
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：

```bash
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](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/skills.md)。

## 安装效果

安装完成后，项目将获得完整的 AI 协作基础设施：

```text
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/`](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/README.md)：

-   [过程数据归档](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/process-data.md) — 采集、校验、审计、修复、导出、隐私与备份指南
-   [架构概览](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/architecture.md) — 引导 CLI、端到端流程、分层架构
-   [平台支持](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/platform-support.md) — macOS、Linux、Windows；沙箱引擎与资源配置
-   [沙箱](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/sandbox.md) — 沙箱 aliases、宿主-沙箱文件交换、用户级 dotfiles 通道
-   [Benchmark 契约与威胁模型](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/benchmark.md) — 版本化 benchmark schema、信任边界与安全保证
-   [飞书桥接](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/feishu-bridge.md) — 配置飞书长连接 adapter、命令路由、权限和 TUI 选择
-   [内置 AI Skills](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/skills.md) — 按使用场景分组的完整 skill 清单
-   [自定义 Skills](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/custom-skills.md) — 创建并同步项目专属 skill
-   [自定义工具调用](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/custom-tool-invocations.md) — 配置自定义工具的下一步命令
-   [预置工作流](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/workflows.md) — 分阶段交付链路与示例流程
-   [配置参考](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/configuration.md) — `.agents/.airc.json`、外部源、版本管理
-   [文件管理策略](https://npmcn.com/package/%40fitlab-ai/agent-infra/docs/zh-CN/file-management.md) — managed / merged / ejected 更新策略

## 参与贡献

开发规范请参阅 [CONTRIBUTING.zh-CN.md](https://npmcn.com/package/%40fitlab-ai/agent-infra/CONTRIBUTING.zh-CN.md)。

## 许可协议

[MIT](https://npmcn.com/package/%40fitlab-ai/agent-infra/License.txt)

## 社区

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

![FitFramework 微信公众号二维码](https://npmcn.com/package/%40fitlab-ai/agent-infra/assets/qrcode_for_wechat_gh.png) ![FitFramework QQ 技术交流群二维码](https://npmcn.com/package/%40fitlab-ai/agent-infra/assets/qrcode_for_qq_01.png)

## 常见问题

### @fitlab-ai/agent-infra 是什么？

AI多工具协作基础设施的启动工具——与克洛德码,Codex,Antigravity CLI和OpenCode合作

### 如何安装 @fitlab-ai/agent-infra？

在项目目录运行 npm install @fitlab-ai/agent-infra，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ai、agent-infra、agent-infra-internal，可以用 npx ai 直接运行。

### @fitlab-ai/agent-infra 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fitlab-ai/agent-infra 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fitlab-ai/agent-infra 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.9\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fitlab-ai/agent-infra 可以商用吗？

@fitlab-ai/agent-infra 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fitlab-ai/agent-infra 的下载量有多少？

根据 npm 官方下载统计，@fitlab-ai/agent-infra 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,395 次，日均约 80 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fitlab-ai/agent-infra 还在维护吗？

最新版本 0\.12\.4 发布于 2026/11/13（2 天前）；至今共发布 79 个版本，其中过去 12 个月发布了 79 个；首次发布于 2026/03/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。