forge

_{Forge Pulse —— 全局任务质量面板（跨项目事件流 / 任务评分与证据链 / Skills 聚合）}

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

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

✨ 核心功能

🚀 快速开始

需要 Claude Code 已安装。

# 安装
npm install -g @agent_forge/forge

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

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

forge init 不在项目目录写任何文件（不会被 git add 误提交），全部资产落在用户级：

团队要 git 共享同一份协议？ 用 forge init --project（团队模式）——.forge/protocol.yml、CLAUDE.md、AGENTS.md 等指令资产写入项目目录可提交共享；再跑一次普通 forge init 即转回零写入。

主要用 Claude Code？ 走 plugin marketplace 一次性接线用户级 hooks（机器上所有项目共享，连 ~/.claude/settings.json 都不用动）。

🔧 它如何工作

        ┌──────────────────────────────────────────────────┐
        │                coding agent                       │
        │        (Claude Code / Codex / Cursor ...)         │
        └────────────────────┬─────────────────────────────┘
                             │ 每次 Write / Edit / Bash
                             ▼
        ┌──────────────────────────────────────────────────┐
        │            Forge Hooks · 实时拦截                 │
        │   task-guard · read-before-edit · bash-guard      │
        │   hazard-guard · file-sentinel · cheat-scan       │
        └────────────────────┬─────────────────────────────┘
                             │
                             ▼
        ┌──────────────────────────────────────────────────┐
        │           任务门禁 · 持久化状态                    │
        │    task-implement → task-verify → task-complete   │
        └────────────────────┬─────────────────────────────┘
                             │
                             ▼
                📊 质量评分 + deterministic 证据链

每轮 AI 编码循环都被门禁兜底：编译是否通过、断言有没有被弱化、改代码前是否真读过、文件有没有被绕道篡改——循环跑得越快，越需要自动化验证，而不是靠人盯着。

🎯 定位：Loop Engineering 的验证 / 状态层

AI 编码是一个循环：写代码 → 运行 → 读反馈 → 修正 → 再写。这个循环由 coding agent（Claude Code、Codex）驱动，Forge 不替代循环本身——它补上循环最容易缺的两层：

• 验证层 — 每一轮产出物经门禁检验：编译通过、断言没被弱化、改代码前确实读过代码、文件未被绕道篡改。循环跑得越快，越需要自动化验证兜底，而不是靠人盯着。
• 状态层 — 跨循环的任务状态：3 道门禁（实现 → 验证 → 完成）、活跃任务追踪、门禁历史。"做到哪了 / 是否达标"有持久化、可审计的记录，而不是只活在 agent 的上下文里（上下文一压缩就丢）。

换言之，coding agent 负责跑循环，Forge 负责让每一轮循环产出可信、状态可追。Forge 不 discovery、不规划需求——那些是循环前端的事；Forge 守的是循环的执行质量。

🔧 工作流程

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

forge task start --ref feat/add-login --branch --accept "go test -v ./... :: PASS"   # 创建任务+分支+登记验收标准（--accept 可重复；Expected 是输出子串匹配，go test 需 -v 才含 PASS 字样）
forge task start --ref feat/add-login --scope "internal/auth/*.go"                # 声明计划改动白名单（规划前置→可度量契约，advisory 检测 scope-drift）
forge task start --ref feat/frontend --assignee kimi --role frontend --depends-on feat/api   # 创建即分派给 kimi（offered），声明上游依赖 feat/api（DAG 环检测；task-verify/task-complete 在 feat/api 交付前阻断）
forge task start --ref feat/hotfix --assignee kimi --ttl 24h   # per-task TTL 覆盖全局 7d 僵尸窗口：短时效分派 24h 无活动即标僵尸（offered/claimed/input-required 通用；0=用全局默认）
# AI 自动完成工作...
forge task gate task-implement    # ✅ 代码实现（advisory：编译/断言提醒，agent 自检）
forge task verify-acceptance      # ✅ 实跑验收标准，记 deterministic 证据（spec-as-gate）
forge task gate task-verify       # ✅ 测试验证
forge task scope show             # 查看声明白名单 + 实时 scope-drift（advisory，不阻塞）
forge task gate task-complete     # ✅ 完成确认（第三道门禁；门禁全过 ≠ 任务完结）
forge task complete               # 🏁 任务完结：MarkComplete + 自动评分 + Act 结论 + 清 active ref（2026-08-18 死锁修复后完成标记归属本命令——门禁只过不 complete 会留僵尸任务）
forge task score                  # 查看质量评分

🪝 Hook 系统

Forge 通过 Claude Code 的 Hook 机制实现实时质量检查。三层纵深防御，监控的是文件而非工具：

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

Layer 2: PostToolUse 文件监控
  └─ file-sentinel: Bash → 对比执行前后 git 状态，未授权变更自动 revert

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

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

📋 命令参考

📦 安装

# 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)

/plugin marketplace add MjxUpUp/Forge
/plugin install forge@forge

🤝 贡献

欢迎提 Issue 和 PR。开发时注意：

1. 门禁先行 —— 任何源码变更走 forge task 三门禁（implement → verify → complete），不经任务的改动不被质量评分追踪。
2. 注释双语 —— Go godoc 采用形式 A（英文段 → 空 // → 中文段），中文不删、不单语；行内注释与字符串字面量不动。
3. 审查闭环 —— 提交前派独立只读子 agent 跑 code-review-gate 双轨（AI 作弊 + 工程规范），forge review pass 标记后才能过 task-complete 门禁。
4. 提交纪律 —— 只提交源码变更；排除 docs/、设计文档、.claude/、.forge/ 工作目录。

详见质量协议（由 forge init 生成到用户级 ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md；生成器源码在 internal/skillgen/）。

📚 更多文档

License

Apache-2.0