@agent_forge/forge 1.84.5 → 1.85.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +19 -47
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -2,39 +2,37 @@
2
2
 
3
3
  AI 写的代码,你放心直接提交吗?
4
4
 
5
- Forge 在 AI 编码过程中自动插入结构化质量门禁——从任务创建到代码提交,确保每一步产出物都经过验证。配合 Claude Code 的 Hook 系统实现实时拦截,不需要你手动检查。
5
+ Forge 在 AI 编码过程中插入结构化质量门禁——从任务创建到代码提交,确保每一步产出物都经过验证。质量检查在 `forge task gate` / `forge change verify` 进程内执行,没有实时拦截层,写操作不经过 forge。
6
6
 
7
7
  ## 核心功能
8
8
 
9
9
  - **任务级门禁** — 每个开发任务走 3 道门禁:实现 → 验证 → 完成
10
- - **实时 Hook 拦截** — 27 个内置 Hook,在 AI 写代码的同时自动检查质量、防止绕过
11
- - **安全纵深防御** — 三层防御架构:工具拦截 → 文件监控 → 自身保护
10
+ - **change 证据封印** — `forge change verify` 实跑 acceptance 判据,证据绑定 commit/diff 并随仓库走
11
+ - **无拦截层** — 写操作不经过 forge,质量只能由 gate/verify 与 CI 检查(`forge change check`)
12
12
  - **质量评分** — 每个任务完成后自动评分,量化 AI 编码质量
13
13
 
14
14
  ## 快速开始
15
15
 
16
- 需要 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 已安装。
17
-
18
16
  ```bash
19
17
  # 安装
20
18
  npm install -g @agent_forge/forge
21
19
 
22
- # 在项目目录初始化(默认零项目写入)
20
+ # 在仓库里声明 forge 契约(只写仓库内产物)
23
21
  cd your-project
24
22
  forge init
25
23
 
26
- # 在 Claude Code 中开始工作
27
- # AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程
24
+ # 可选:登记进全局看板
25
+ forge registry add .
28
26
  ```
29
27
 
30
- `forge init` 不在项目目录写任何文件,全部资产落在用户级:
31
- - `~/.forge/projects.json` — 全局项目注册表
32
- - `~/.forge/projects/<key>/` — protocol.yml + runtime state(任务状态/hook 参考副本)
33
- - `~/.claude/settings.json` — Claude Code hooks(plugin 已装则由 plugin 接管)
34
- - `~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md` — 质量协议(备份+追加,`forge uninstall --restore` 可回滚)
35
- - `~/.claude/skills/forge-quality/` — 质量协议 Skill
28
+ `forge init` 只写仓库内产物,**不写** `~/.forge`、`~/.claude`、`~/.codex`:
29
+ - `spec/forge.yaml` — 契约(profile 缺省 mini、`hooks: off` 兼容字段)
30
+ - `spec/changes/`(含 `archive/`) — change 生命周期产物
31
+ - `AGENTS.md` — forge 托管块;已存在的 `CLAUDE.md` / `.cursor/rules/` 按默认规则补指针
32
+
33
+ forge **没有宿主层**:不分发宿主插件、不写宿主配置。任务与 change 门禁由 agent 在 shell 里显式跑 `forge task` / `forge change` 命令;需要全局视图(`dashboard`、`task list --open --all-projects`)时用 `forge registry add` 显式登记。
36
34
 
37
- 团队要 git 共享协议用 `forge init --project`(团队模式,指令资产写项目目录)。
35
+ 团队要 git 共享契约:提交 `spec/` 与 `AGENTS.md`。
38
36
 
39
37
  ## 工作流程
40
38
 
@@ -54,39 +52,13 @@ forge task score # 查看质量评分
54
52
 
55
53
  门禁之间有时间和活动检查,防止 AI 跳过阶段直接提交。`task-implement` 的编译/断言检查为 advisory 提醒(agent 自检,不阻塞)——forge 技术栈无关,适配 loop engineering。
56
54
 
57
- ## Hook 系统
58
-
59
- Forge 通过 Claude Code 的 Hook 机制实现实时质量检查(主要 Hook 如下,完整 27 个清单见 [Hook 参考](https://github.com/MjxUpUp/Forge/blob/main/docs/reference/hooks.md)):
60
-
61
- | Hook | 触发时机 | 功能 |
62
- |------|----------|------|
63
- | **task-guard** | Write/Edit 前 | 无活跃任务时 WARN(仅 `.forge/*`/`.claude/settings*` 自保护 FAIL——此类项目级文件只在团队模式/老项目存在),保护 Forge 配置不被篡改 |
64
- | **assertion-check** | Write/Edit 前 | 检测断言弱化(t.Fatal → t.Log、assert! 被删除等),advisory 提醒不阻塞(agent 自检) |
65
- | **bash-guard** | Bash 前 | 检测命令中的写文件模式(writeFile、cat >、sed -i 等),无任务时 WARN(源码随后被 file-sentinel 隔离) |
66
- | **auto-compile** | Write/Edit 后 | advisory 提醒用对应技术栈编译命令自检(go build / cargo check / mvn / tsc 等),不强制编译 |
67
- | **file-sentinel** | Bash 后 | 监控文件变更,未授权修改隔离到 DataDir/quarantine/(`forge data-dir` 查看路径,可恢复,不删除) |
68
- | **tool-track** | Read/Skill/Agent/Grep/Glob/Bash 后 | 静默记录工具调用到 toollog(Read/Skill/Agent 记名称、Bash 记截断命令、Grep/Glob 记截断 input——探索调用也计入 work-activity),供 read-before-edit 门禁与 efficiency 维度评分判断(agent 是否先读代码再改、质量 skill 是否被驱动) |
69
- | **task-verify** | 会话结束 | 任务门禁/主分支保护到 stderr+checklog(advisory);活跃任务 + 未提交代码变更时有界阻断 Stop(每会话最多 3 次,超限回落 advisory;逃生 `FORGE_TASK_VERIFY_STOP=0`) |
70
- | **skill-scan** | 会话开始 | advisory:扫描 ~/.claude/skills 安全性(`forge skills audit`,21 条安全规则),补 install 门控缺口(手动 clone/junction/git pull 进入的 skill),全局 hook 不依赖 forge project |
71
- | **task-resume** | 会话开始 | advisory:只输出 `[forge-session]` 管理横幅一行(不注入接续视图、不锚定 session)。接续按需拉取:`forge task resume --match` / `forge task list --open`;无活跃任务静默;项目级 hook |
72
-
73
- ### 安全架构
55
+ ## 质量检查
74
56
 
75
- 三层纵深防御,监控的是文件而非工具:
57
+ 检查由 `forge task gate` / `forge change verify` 在进程内确定性执行(编译自检、断言弱化扫描、测试伴随变更、证据封印)。
76
58
 
77
- ```
78
- Layer 1: PreToolUse 快速拦截
79
- ├─ task-guard: Write/Edit → 检查任务状态 + 自保护(forge 配置层)
80
- └─ bash-guard: Bash → 检测写文件模式
81
-
82
- Layer 2: PostToolUse 文件监控
83
- └─ file-sentinel: Bash → 对比执行前后 git 状态,未授权变更隔离到 quarantine(可恢复,不删除)
84
-
85
- Layer 3: 会话结束验证
86
- └─ task-verify: 检查任务完成度 + 主分支保护 + 自身版本
87
- ```
59
+ ## 安全边界
88
60
 
89
- 活跃任务内,Agent 无法通过 `node -e "fs.writeFileSync()"`、`cat > file`、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层,file-sentinel 监控文件层,task-guard 保护配置层;无活跃任务时 task-guard 只 WARN。
61
+ 没有拦截层:写操作不经过 forge,绕过只能靠 CI required check 与 review。`forge change check` 校验每个未归档 change 的证据与当前代码一致;要在 GitHub 上真拦住合并,需把对应 workflow 设为 required status check。
90
62
 
91
63
  ## 命令参考
92
64
 
@@ -94,9 +66,9 @@ Layer 3: 会话结束验证
94
66
 
95
67
  | 命令 | 说明 |
96
68
  |------|------|
97
- | `forge init` | 初始化项目(默认零项目写入:登记全局注册表,hooks/指令/skill 全在用户级;`--project` 团队模式把指令资产写项目目录供 git 共享;旧的 `--mode` 标志已废弃为 no-op) |
69
+ | `forge init [--profile mini\|standard\|full]` | 在仓库声明契约:只写 `spec/forge.yaml`、`spec/changes/`、`AGENTS.md` 托管块与已存在指针,不写用户主目录;`--project` 已废弃为 no-op(保留旧脚本兼容) |
98
70
  | `forge status [--json]` | 查看项目状态(任务管道 + 质量信号) |
99
- | `forge verify` | 项目完整性检查 + 回归测试 |
71
+ | `forge verify` | 校验仓库契约 `spec/forge.yaml` |
100
72
  | `forge update` | 检查并更新到最新版本(按安装通道分流:npm 安装查 npm registry 并打印对应包管理器的更新命令——npm 包不可变,不做原地替换;GitHub Release 安装则从 GitHub 下载自替换) |
101
73
 
102
74
  ### 任务管理
package/package.json CHANGED
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "name": "@agent_forge/forge",
3
- "version": "1.84.5",
3
+ "version": "1.85.0",
4
4
  "description": "AI 开发质量门禁引擎 — 结构化门禁管道,在 AI 生成的代码进入仓库前进行质量锻造",
5
5
  "bin": {
6
6
  "forge": "run.js"
7
7
  },
8
8
  "optionalDependencies": {
9
- "@agent_forge/forge-darwin-arm64": "1.84.5",
10
- "@agent_forge/forge-darwin-x64": "1.84.5",
11
- "@agent_forge/forge-linux-arm64": "1.84.5",
12
- "@agent_forge/forge-linux-x64": "1.84.5",
13
- "@agent_forge/forge-win32-x64": "1.84.5"
9
+ "@agent_forge/forge-darwin-arm64": "1.85.0",
10
+ "@agent_forge/forge-darwin-x64": "1.85.0",
11
+ "@agent_forge/forge-linux-arm64": "1.85.0",
12
+ "@agent_forge/forge-linux-x64": "1.85.0",
13
+ "@agent_forge/forge-win32-x64": "1.85.0"
14
14
  },
15
15
  "files": [
16
16
  "run.js",