# @agent\_forge/forge 中文文档

规范地址：https://npmcn.com/package/%40agent_forge/forge/

版本：1\.84\.5
npm 元数据更新时间：2026-10-25T13:02:33.860Z
中文译文更新时间：2026-11-06T16:06:30.227Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40agent_forge/forge
原文对照：https://npmcn.com/package/%40agent_forge/forge/?lang=original
项目主页：https://github.com/MjxUpUp/Forge#readme
源码仓库：https://github.com/MjxUpUp/Forge

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

- 包体积（解压后）：14.2 kB，3 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=16
- 运行依赖：0 个
- 首次发布：2026-06-27T11:02:31.999Z
- 最新版本发布：2026-10-25T13:02:33.338Z
- 近 30 天下载量：2781（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：143（近 12 个月 143 个）

## 中文简介

AI 开发质量门禁引擎 — 结构化门禁管道，在 AI 生成的代码进入仓库前进行质量锻造

## 安装

```sh
npm install @agent_forge/forge
```

也可以使用：`pnpm add @agent_forge/forge`、`yarn add @agent_forge/forge`、`bun add @agent_forge/forge`

## README

# Forge — AI 开发质量门禁引擎

AI 写的代码，你放心直接提交吗？

Forge 在 AI 编码过程中自动插入结构化质量门禁——从任务创建到代码提交，确保每一步产出物都经过验证。配合 Claude Code 的 Hook 系统实现实时拦截，不需要你手动检查。

## 核心功能

-   **任务级门禁** — 每个开发任务走 3 道门禁：实现 → 验证 → 完成
-   **实时 Hook 拦截** — 27 个内置 Hook，在 AI 写代码的同时自动检查质量、防止绕过
-   **安全纵深防御** — 三层防御架构：工具拦截 → 文件监控 → 自身保护
-   **质量评分** — 每个任务完成后自动评分，量化 AI 编码质量

## 快速开始

需要 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 已安装。

```bash
# 安装
npm install -g @agent_forge/forge

# 在项目目录初始化（默认零项目写入）
cd your-project
forge init

# 在 Claude Code 中开始工作
# AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程
```

`forge init` 不在项目目录写任何文件，全部资产落在用户级：

-   `~/.forge/projects.json` — 全局项目注册表
-   `~/.forge/projects/<key>/` — protocol.yml + runtime state（任务状态/hook 参考副本）
-   `~/.claude/settings.json` — Claude Code hooks（plugin 已装则由 plugin 接管）
-   `~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` — 质量协议（备份+追加，`forge uninstall --restore` 可回滚）
-   `~/.claude/skills/forge-quality/` — 质量协议 Skill

团队要 git 共享协议用 `forge init --project`（团队模式，指令资产写项目目录）。

## 工作流程

### 任务级门禁

每个开发任务自动走 3 道门禁：

```bash
forge task start --ref feat/add-login --branch   # 创建任务 + 分支
# AI 自动完成工作...
forge task gate task-implement    # ✅ 代码实现（advisory：编译/断言自检提醒）
forge task gate task-verify       # ✅ 测试验证
forge task gate task-complete     # ✅ 完成确认
forge task complete               # 🏁 任务完结（自动评分 + 清 active ref；git commit 在此之前）
forge task score                  # 查看质量评分
```

门禁之间有时间和活动检查，防止 AI 跳过阶段直接提交。`task-implement` 的编译/断言检查为 advisory 提醒（agent 自检，不阻塞）——forge 技术栈无关，适配 loop engineering。

## Hook 系统

Forge 通过 Claude Code 的 Hook 机制实现实时质量检查（主要 Hook 如下，完整 27 个清单见 [Hook 参考](https://github.com/MjxUpUp/Forge/blob/main/docs/reference/hooks.md)）：

| Hook | 触发时机 | 功能 |
| --- | --- | --- |
| **task-guard** | Write/Edit 前 | 无活跃任务时 WARN（仅 `.forge/*`/`.claude/settings*` 自保护 FAIL——此类项目级文件只在团队模式/老项目存在），保护 Forge 配置不被篡改 |
| **assertion-check** | Write/Edit 前 | 检测断言弱化（t.Fatal → t.Log、assert! 被删除等），advisory 提醒不阻塞（agent 自检） |
| **bash-guard** | Bash 前 | 检测命令中的写文件模式（writeFile、cat >、sed -i 等），无任务时 WARN（源码随后被 file-sentinel 隔离） |
| **auto-compile** | Write/Edit 后 | advisory 提醒用对应技术栈编译命令自检（go build / cargo check / mvn / tsc 等），不强制编译 |
| **file-sentinel** | Bash 后 | 监控文件变更，未授权修改隔离到 DataDir/quarantine/（`forge data-dir` 查看路径，可恢复，不删除） |
| **tool-track** | Read/Skill/Agent/Grep/Glob/Bash 后 | 静默记录工具调用到 toollog（Read/Skill/Agent 记名称、Bash 记截断命令、Grep/Glob 记截断 input——探索调用也计入 work-activity），供 read-before-edit 门禁与 efficiency 维度评分判断（agent 是否先读代码再改、质量 skill 是否被驱动） |
| **task-verify** | 会话结束 | 任务门禁/主分支保护到 stderr+checklog（advisory）；活跃任务 + 未提交代码变更时有界阻断 Stop（每会话最多 3 次，超限回落 advisory；逃生 `FORGE_TASK_VERIFY_STOP=0`） |
| **skill-scan** | 会话开始 | advisory：扫描 ~/.claude/skills 安全性（`forge skills audit`，21 条安全规则），补 install 门控缺口（手动 clone/junction/git pull 进入的 skill），全局 hook 不依赖 forge project |
| **task-resume** | 会话开始 | advisory：只输出 `[forge-session]` 管理横幅一行（不注入接续视图、不锚定 session）。接续按需拉取：`forge task resume --match` / `forge task list --open`；无活跃任务静默；项目级 hook |

### 安全架构

三层纵深防御，监控的是文件而非工具：

```
Layer 1: PreToolUse 快速拦截
  ├─ task-guard: Write/Edit → 检查任务状态 + 自保护（forge 配置层）
  └─ bash-guard: Bash → 检测写文件模式

Layer 2: PostToolUse 文件监控
  └─ file-sentinel: Bash → 对比执行前后 git 状态，未授权变更隔离到 quarantine（可恢复，不删除）

Layer 3: 会话结束验证
  └─ task-verify: 检查任务完成度 + 主分支保护 + 自身版本
```

活跃任务内，Agent 无法通过 `node -e "fs.writeFileSync()"`、`cat > file`、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层，file-sentinel 监控文件层，task-guard 保护配置层；无活跃任务时 task-guard 只 WARN。

## 命令参考

### 项目管理

| 命令 | 说明 |
| --- | --- |
| `forge init` | 初始化项目（默认零项目写入：登记全局注册表，hooks/指令/skill 全在用户级；`--project` 团队模式把指令资产写项目目录供 git 共享；旧的 `--mode` 标志已废弃为 no-op） |
| `forge status [--json]` | 查看项目状态（任务管道 + 质量信号） |
| `forge verify` | 项目完整性检查 + 回归测试 |
| `forge update` | 检查并更新到最新版本（按安装通道分流：npm 安装查 npm registry 并打印对应包管理器的更新命令——npm 包不可变，不做原地替换；GitHub Release 安装则从 GitHub 下载自替换） |

### 任务管理

| 命令 | 说明 |
| --- | --- |
| `forge task start --ref <type/desc> --branch` | 创建任务（自动创建分支） |
| `forge task status` | 查看当前任务门禁状态 |
| `forge task list` | 列出所有任务 |
| `forge task gate <gate-id>` | 验证单道任务门禁 |
| `forge task complete` | 标记任务完成（自动评分） |
| `forge task score` | 查看任务质量评分 |

## 安装

```bash
# npm（推荐）
npm install -g @agent_forge/forge

# 或从 GitHub Releases 下载二进制
# https://github.com/MjxUpUp/Forge/releases

# 支持平台：macOS (x86_64/ARM64)、Linux (x86_64/ARM64)、Windows (x86_64)
```

## License

Apache-2.0

## 常见问题

### @agent\_forge/forge 是什么？

AI 开发质量门禁引擎 — 结构化门禁管道，在 AI 生成的代码进入仓库前进行质量锻造

### 如何安装 @agent\_forge/forge？

在项目目录运行 npm install @agent\_forge/forge，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 forge，可以用 npx forge 直接运行。

### @agent\_forge/forge 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agent\_forge\_\_forge 是否存在。

### @agent\_forge/forge 需要什么版本的 Node\.js？

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

### @agent\_forge/forge 可以商用吗？

@agent\_forge/forge 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agent\_forge/forge 的下载量有多少？

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

### @agent\_forge/forge 还在维护吗？

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