@agent_forge/forge 0.27.0

package/README.md

@@ -0,0 +1,158 @@
+# Forge — AI 开发质量门禁引擎
+
+AI 写的代码，你放心直接提交吗？
+
+Forge 在 AI 编码过程中自动插入结构化质量门禁——从任务创建到代码提交，确保每一步产出物都经过验证。配合 Claude Code 的 Hook 系统实现实时拦截，不需要你手动检查。
+
+## 核心功能
+
+- **项目级管道** — 从需求定义到发布的全流程质量门禁，按项目规模自动选择
+- **任务级门禁** — 每个开发任务走 5 道轻量门禁：理解 → 方案 → 实现 → 验证 → 完成
+- **实时 Hook 拦截** — 8 个内置 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 会创建：
+- `.forge/` — 管道定义、Hook 脚本、任务状态
+- `.claude/settings.local.json` — Hook 集成配置
+- `.claude/CLAUDE.md` — 质量协议引用
+- `.claude/skills/` — 管道编排 Skill
+
+## 工作流程
+
+### 项目级管道
+
+```
+forge init → 自动检测项目规模 → 生成门禁管道
+
+gate-1-prd (需求定义) → gate-3-plan (实现计划) → gate-4-implement (代码实现) → gate-5-test (测试验证) → gate-6-acceptance (项目验收)
+```
+
+`forge init` 根据项目规模自动选择门禁数量（small / medium / large），`forge status` 查看所有启用的 gate。
+
+### 任务级门禁
+
+每个开发任务自动走 3 道门禁：
+
+```bash
+forge task start --ref feat/add-login --branch   # 创建任务 + 分支
+# AI 自动完成工作...
+forge task gate task-implement    # ✅ 代码实现（自动检查编译 + 断言）
+forge task gate task-verify       # ✅ 测试验证
+forge task gate task-complete     # ✅ 完成确认
+forge task score                  # 查看质量评分
+```
+
+门禁之间有时间和活动检查，防止 AI 跳过阶段直接提交。`task-implement` 是自动门禁，会检查编译通过和断言未被弱化。
+
+## Hook 系统
+
+Forge 通过 Claude Code 的 Hook 机制实现实时质量检查：
+
+| Hook | 触发时机 | 功能 |
+|------|----------|------|
+| **task-guard** | Write/Edit 前 | 无活跃任务时 WARN（仅 `.forge/*` 自保护文件 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 后 | 监控文件变更，未授权修改隔离到 .forge/quarantine/（可恢复，不删除） |
+| **tool-track** | Read 后 | 静默记录 Read 调用到 toollog，供 task-verify 的 read-before-edit 门禁判断（agent 是否先读代码再改） |
+| **task-verify** | 会话结束 | advisory：任务门禁/主分支保护/mandatory review 提醒到 stderr+checklog（不阻塞会话结束） |
+| **skill-scan** | 会话开始 | advisory：扫描 ~/.claude/skills 安全性（forge audit 19 规则），补 install 门控缺口（手动 clone/junction/git pull 进入的 skill），全局 hook 不依赖 forge project |
+
+### 安全架构
+
+三层纵深防御，监控的是文件而非工具：
+
+```
+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 保护配置层。
+
+## 命令参考
+
+### 项目管理
+
+| 命令 | 说明 |
+|------|------|
+| `forge init [--mode small\|medium\|large]` | 初始化管道（自动检测项目规模） |
+| `forge status [--json]` | 查看管道状态 |
+| `forge gate <gate-id>` | 验证指定门禁 |
+| `forge validate` | 检查 pipeline.yml 配置 |
+| `forge verify` | 项目完整性检查 + 回归测试 |
+| `forge snapshot` | 检测项目开发阶段 |
+| `forge update` | 自更新到最新版本 |
+
+### 任务管理
+
+| 命令 | 说明 |
+|------|------|
+| `forge task start --ref <type/desc> --branch` | 创建任务（自动创建分支） |
+| `forge task status` | 查看当前任务门禁状态 |
+| `forge task list` | 列出所有任务 |
+| `forge task gate <gate-id>` | 验证单道任务门禁 |
+| `forge task complete` | 标记任务完成（自动评分） |
+| `forge task score` | 查看任务质量评分 |
+
+### 经验库
+
+| 命令 | 说明 |
+|------|------|
+| `forge experience list` | 查看经验条目 |
+| `forge knowledge` | 跨项目经验库管理 |
+
+## 安装
+
+```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)
+```
+
+## 项目门禁管道
+
+| Gate ID | 名称 | small | medium | large |
+|---------|------|:-----:|:------:|:-----:|
+| gate-1-prd | 需求定义 | ✓ | ✓ | ✓ |
+| gate-3-plan | 实现计划 | ✓ | ✓ | ✓ |
+| gate-4-implement | 代码实现 | | ✓ | ✓ |
+| gate-5-test | 测试验证 | | ✓ | ✓ |
+| gate-6-acceptance | 项目验收 | | ✓ | ✓ |
+| gate-8-release | 发布 | | | ✓ |
+| gate-0-research | 立项调研 | | | ✓ |
+| gate-2-design | 技术方案 | | | ✓ |
+| gate-7-archive | 经验归档 | | | ✓ |
+
+## License
+
+Apache-2.0

package/install.js

@@ -0,0 +1,182 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const { createWriteStream } = require("fs");
+const { pipeline } = require("stream/promises");
+
+const VERSION = require("./package.json").version;
+
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const osMap = { darwin: "darwin", linux: "linux", win32: "windows" };
+  const archMap = { x64: "x86_64", arm64: "aarch64" };
+
+  const goos = osMap[platform];
+  const goarch = archMap[arch];
+
+  if (!goos || !goarch) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+
+  return { goos, goarch };
+}
+
+function getBinaryName() {
+  return process.platform === "win32" ? "forge.exe" : "forge";
+}
+
+async function download(url, dest) {
+  let lastError;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    if (attempt > 0) {
+      const delay = Math.min(1000 * Math.pow(2, attempt), 8000);
+      console.log(`Retrying (${attempt + 1}/3) after ${delay / 1000}s...`);
+      await new Promise((r) => setTimeout(r, delay));
+    }
+
+    try {
+      let currentUrl = url;
+      while (true) {
+        const res = await new Promise((resolve, reject) => {
+          https
+            .get(currentUrl, { timeout: 30000 }, resolve)
+            .on("error", reject);
+        });
+
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.destroy();
+          currentUrl = res.headers.location;
+          continue;
+        }
+        if (res.statusCode !== 200) {
+          res.destroy();
+          throw new Error(`Download failed: HTTP ${res.statusCode}`);
+        }
+
+        await pipeline(res, createWriteStream(dest));
+        return;
+      }
+    } catch (err) {
+      lastError = err;
+      // Clean up partial download
+      try { fs.unlinkSync(dest); } catch (_) {}
+    }
+  }
+  throw lastError || new Error("Download failed after 3 attempts");
+}
+
+/**
+ * Check if an existing binary matches the target version.
+ * Runs `forge --version` and parses the version string.
+ */
+function existingBinaryMatches(binaryPath) {
+  try {
+    const output = execSync(`"${binaryPath}" --version`, {
+      timeout: 5000,
+      stdio: "pipe",
+      env: { ...process.env, FORGE_SKIP_UPDATE_CHECK: "1" },
+    }).toString().trim();
+    // Output format: "forge version 0.14.4 (commit: ...)" or "forge version dev"
+    const match = output.match(/forge version (\S+)/);
+    return match && match[1] === VERSION;
+  } catch (_) {
+    return false;
+  }
+}
+
+async function main() {
+  const binDir = path.join(__dirname, "bin");
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const binaryName = getBinaryName();
+  const binaryPath = path.join(binDir, binaryName);
+
+  // Skip download if existing binary already matches the target version.
+  // This avoids "file busy" errors on Windows when upgrading while
+  // forge hooks are actively running in another Claude Code session.
+  if (existingBinaryMatches(binaryPath)) {
+    console.log(`forge v${VERSION} already installed.`);
+    return;
+  }
+
+  const { goos, goarch } = getPlatform();
+  const archiveName = `forge_${VERSION}_${goos}_${goarch}.tar.gz`;
+
+  // Support custom binary host for regions with poor GitHub connectivity.
+  // Usage: FORGE_BINARY_HOST=https://mirror.example.com npm install -g @agent_forge/forge
+  const baseUrl = process.env.FORGE_BINARY_HOST
+    || "https://github.com/MjxUpUp/Forge/releases/download";
+  const url = `${baseUrl}/v${VERSION}/${archiveName}`;
+
+  const archivePath = path.join(binDir, archiveName);
+  console.log(`Downloading forge v${VERSION} for ${goos}/${goarch}...`);
+
+  await download(url, archivePath);
+  console.log(`Downloaded to ${archivePath}`);
+
+  // Extract using relative path (cwd=binDir) to avoid Windows tar
+  // interpreting "X:/path" as a remote host connection.
+  //
+  // On Windows, if forge.exe is currently running (e.g. another Claude Code
+  // session has hooks active), tar cannot overwrite it. Handle this by:
+  // 1. Renaming the old binary to .old (preserves running process)
+  // 2. Extracting the new binary
+  // 3. Cleaning up archive
+  // The run.js wrapper will recover from .old on next launch if needed.
+  let renamedOld = false;
+  if (process.platform === "win32" && fs.existsSync(binaryPath)) {
+    const oldPath = binaryPath + ".old";
+    try { fs.unlinkSync(oldPath); } catch (_) {}
+    try {
+      fs.renameSync(binaryPath, oldPath);
+      renamedOld = true;
+    } catch (_) {
+      // Cannot rename either — will try extract anyway
+    }
+  }
+
+  try {
+    execSync(`tar xzf "${archiveName}"`, { cwd: binDir, stdio: "pipe", timeout: 30000 });
+  } catch (err) {
+    // Extract failed — likely file busy on Windows
+    if (renamedOld) {
+      // Restore old binary so the package isn't left broken
+      const oldPath = binaryPath + ".old";
+      try {
+        if (!fs.existsSync(binaryPath)) {
+          fs.renameSync(oldPath, binaryPath);
+          console.error(`[forge] Extract failed, restored previous binary. Will upgrade on next launch.`);
+        }
+      } catch (_) {}
+    }
+    throw new Error(
+      `Failed to extract binary (file may be in use). ` +
+      `Close other Claude Code sessions and run: npm install -g @agent_forge/forge`
+    );
+  }
+
+  // Make executable (Unix)
+  if (process.platform !== "win32") {
+    fs.chmodSync(binaryPath, 0o755);
+  }
+
+  // Cleanup archive and .old backup
+  fs.unlinkSync(archivePath);
+  if (renamedOld) {
+    try { fs.unlinkSync(binaryPath + ".old"); } catch (_) {}
+  }
+
+  console.log(`forge v${VERSION} installed successfully.`);
+}
+
+main().catch((err) => {
+  console.error("Installation failed:", err.message);
+  console.error("");
+  console.error("If GitHub is unreachable, set a mirror:");
+  console.error("  FORGE_BINARY_HOST=https://your-mirror.com npm install -g @agent_forge/forge");
+  console.error("");
+  console.error("Or download manually: https://github.com/MjxUpUp/Forge/releases");
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@agent_forge/forge",
+  "version": "0.27.0",
+  "description": "AI 开发质量门禁引擎 — 结构化门禁管道，在 AI 生成的代码进入仓库前进行质量锻造",
+  "bin": {
+    "forge": "run.js"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "install.js",
+    "run.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MjxUpUp/Forge"
+  },
+  "keywords": [
+    "ai",
+    "gate",
+    "pipeline",
+    "quality",
+    "claude-code"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/run.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const { spawn, execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const binaryName = process.platform === "win32" ? "forge.exe" : "forge";
+const binaryPath = path.join(__dirname, "bin", binaryName);
+const oldPath = binaryPath + ".old";
+
+// --- Windows crash recovery (from lark-cli pattern) ---
+// If forge.exe.old exists, we're recovering from an interrupted or failed update.
+function recoverOldBinary() {
+  if (!fs.existsSync(oldPath)) return;
+
+  if (!fs.existsSync(binaryPath)) {
+    // forge.exe missing but .old exists — rename first, then probe.
+    // On Windows, .old is not a recognized executable extension,
+    // so we must restore the .exe name before testing.
+    try {
+      fs.renameSync(oldPath, binaryPath);
+      execSync(`"${binaryPath}" --version`, { timeout: 5000, stdio: "pipe", env: { ...process.env, FORGE_SKIP_UPDATE_CHECK: "1" } });
+      console.error("[forge] Recovered binary from .old backup");
+    } catch (e) {
+      // Restored binary is broken — put it back as .old so we don't lose it
+      try { fs.renameSync(binaryPath, oldPath); } catch (_) {}
+      console.error("[forge] WARNING: .old binary is also broken");
+    }
+  } else {
+    // Both exist — verify current binary works, then clean up .old
+    try {
+      execSync(`"${binaryPath}" --version`, { timeout: 5000, stdio: "pipe", env: { ...process.env, FORGE_SKIP_UPDATE_CHECK: "1" } });
+      fs.unlinkSync(oldPath);
+    } catch (e) {
+      // Current binary broken — replace with .old (rename first, then probe)
+      try { fs.unlinkSync(binaryPath); } catch (_) {}
+      try {
+        fs.renameSync(oldPath, binaryPath);
+        execSync(`"${binaryPath}" --version`, { timeout: 5000, stdio: "pipe", env: { ...process.env, FORGE_SKIP_UPDATE_CHECK: "1" } });
+        console.error("[forge] Recovered binary from .old backup");
+      } catch (e2) {
+        console.error("[forge] WARNING: both binary and .old are broken");
+      }
+    }
+  }
+}
+
+recoverOldBinary();
+
+if (!fs.existsSync(binaryPath)) {
+  // Binary not available (e.g., mid npm upgrade). Silently approve to avoid
+  // blocking Claude Code hooks during installation.
+  console.log('{"decision":"approve"}');
+  process.exit(0);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("exit", (code) => {
+  process.exit(code || 0);
+});