Forge (forge-dsh)

_{30 秒演示（自动播放，静音）—— 画面里的终端输出是真实 forge docs lint 跑出来的：两句没带证据的套话，被拦在提交之前。
带音轨的 1080p 版本在 网页播放器，或直接下 mp4。}

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

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

⚡ 60 秒拿到第一个证据：

forge init
forge task start --ref feat/demo --branch --accept "git log -1 :: commit"
forge task verify-acceptance    # 实跑验收标准 → 不可伪造的 deterministic 证据
forge trace feat/demo           # 查看任务的完整证据链

跑 forge eval wedge-drill 可在任何机器上自检这条首证据路径（隔离环境，60 秒）；forge eval artifact-drill 自检产物链分档执法全链。两者是发版 workflow 的行为级冒烟门禁与 nightly 的每日行为回归。

🎯 它补的是哪一层

AI 编码是一个循环：写代码 → 运行 → 读反馈 → 修正 → 再写。这个循环由 coding agent（Claude Code、Codex、Cursor）驱动，Forge 不替代循环本身，只补上循环最容易缺的两层：验证层（每一轮产出物经门禁检验）与状态层（跨循环的任务状态与门禁历史——上下文一压缩就丢的那种）。

Forge 是 deterministic 的——范围是 "deterministic where code can verify"：行为与意图的正确性留给 review 和人。判据与证据链归产品而非模型厂商，所以这一层不随模型代际贬值；模型变强时该删的是脚手架，不是传感器。

_{完整论述（为什么是确定性门禁而不是让模型自检、退出码三态的设计依据）见 docs/design/positioning.md。}

🔧 它是怎么跑的

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

✨ 核心能力

🚀 快速开始

先装二进制（唯一权威步骤见下方 📦 安装），然后在项目目录：

cd your-project
forge init      # 默认零项目写入，全部资产落在用户级
# 回到 Claude Code 继续工作：AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程

主路径是 Claude Code——hooks 经它的 Hook 机制接线；Codex、Cursor、Windsurf、dsh 等 12 种宿主同样支持（接线差异见 plugins/forge/README.md 与 中文 README）。

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 都不用动）。

📋 命令速查

日常最常用的几条。完整命令表（每个 flag、逃生舱、门禁语义）在 docs/reference/cli.md。

其余命令族（skills、eval、act、workspace、project、registry、harness、compat、plugin、conventions、policy、enforcement、selfcheck、sync、migrate、uninstall、update、node、bridge、docs、worktree、on/off、config、verify、trust）见同一份完整命令表。

🪝 Hook 系统

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

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

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

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

活跃任务内，Agent 无法通过 node -e "fs.writeFileSync()"、cat > file、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层，file-sentinel 监控文件层，task-guard 保护配置层。没有活跃任务时 task-guard 只给 WARN 提示，不是硬墙；有任务才按门禁语义拦截。

27 个内置 Hook 的完整清单（触发时机、职责；可关闭的门禁类都附了逃生开关）见 docs/reference/hooks.md。

📦 安装

# 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」在 Forge 语境指宿主接线打包（分发层，plugins/forge / plugins/forge-dsh），与 dsh/Cordis 的运行时插件同名不同物——辨析见 plugin-philosophy.md。

/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/reference/ 下的参考文档是测试硬依赖， 缺文件整包测试直接红，必须入库；docs/design/ 属设计文档，同样随代码提交）；排除 .claude/、.forge/ 等生成物与临时工作目录。

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

📚 更多文档

License

Apache-2.0