@agent_forge/forge-darwin-x64 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.
- package/bin/README.md +44 -64
- package/bin/forge +0 -0
- package/package.json +1 -1
package/bin/README.md
CHANGED
|
@@ -26,7 +26,7 @@ Stop trusting AI-generated code. Start gating it.
|
|
|
26
26
|
|
|
27
27
|
> **AI 写的代码,你放心直接提交吗?**
|
|
28
28
|
|
|
29
|
-
Forge 在 AI 编码过程中插入结构化质量门禁——从任务创建到代码提交,每一步产出物都要留下 deterministic
|
|
29
|
+
Forge 在 AI 编码过程中插入结构化质量门禁——从任务创建到代码提交,每一步产出物都要留下 deterministic 证据,门禁由 CLI 确定性把关。质量检查只在 `forge task gate` / `forge change verify` 的进程内执行,没有实时拦截层,写操作不经过 forge。
|
|
30
30
|
|
|
31
31
|
**⚡ 60 秒拿到第一个证据**:
|
|
32
32
|
|
|
@@ -54,33 +54,29 @@ Forge 是 deterministic 的——范围是 "deterministic where code can verify"
|
|
|
54
54
|
│ coding agent │
|
|
55
55
|
│ (Claude Code / Codex / Cursor ...) │
|
|
56
56
|
└────────────────────┬─────────────────────────────┘
|
|
57
|
-
│
|
|
57
|
+
│ 显式调用 forge 命令
|
|
58
58
|
▼
|
|
59
59
|
┌──────────────────────────────────────────────────┐
|
|
60
|
-
│
|
|
61
|
-
│ task-guard · read-before-edit · bash-guard │
|
|
62
|
-
│ hazard-guard · file-sentinel · doc-lint │
|
|
63
|
-
└────────────────────┬─────────────────────────────┘
|
|
64
|
-
│
|
|
65
|
-
▼
|
|
66
|
-
┌──────────────────────────────────────────────────┐
|
|
67
|
-
│ 任务门禁 · 持久化状态 │
|
|
60
|
+
│ 任务门禁 · change 验证 │
|
|
68
61
|
│ task-implement → task-verify → task-complete │
|
|
62
|
+
│ 可执行判据 · 证据封印 · 持久化状态 │
|
|
69
63
|
└────────────────────┬─────────────────────────────┘
|
|
70
64
|
│
|
|
71
65
|
▼
|
|
72
66
|
📊 质量评分 + deterministic 证据链
|
|
73
67
|
```
|
|
74
68
|
|
|
69
|
+
<sub>注:forge 没有宿主层;图中的门禁由 agent 显式跑 `forge task` / `forge change` 命令驱动,证据与评分由 CLI 确定性执行。</sub>
|
|
70
|
+
|
|
75
71
|
## ✨ 核心能力
|
|
76
72
|
|
|
77
73
|
<table>
|
|
78
74
|
<tr>
|
|
79
75
|
<td width="50%" valign="top"><strong>🚦 任务级门禁</strong><br/>每个开发任务走 3 道门禁:实现 → 验证 → 完成,门禁之间有活动检查防止跳阶段。</td>
|
|
80
|
-
<td width="50%" valign="top"><strong
|
|
76
|
+
<td width="50%" valign="top"><strong>🔧 显式命令驱动</strong><br/>forge 没有实时拦截层:门禁由 agent 显式跑 forge task / forge change 命令触发,状态与证据落盘可审计。</td>
|
|
81
77
|
</tr>
|
|
82
78
|
<tr>
|
|
83
|
-
<td valign="top"><strong
|
|
79
|
+
<td valign="top"><strong>🧭 质量只由 gate/verify 与 CI 把关</strong><br/>没有拦截层:写操作不经过 forge;质量检查发生在 forge task gate / forge change verify 进程内,合并前由 CI 的 forge change check 兜底。</td>
|
|
84
80
|
<td valign="top"><strong>📊 质量评分</strong><br/>每个任务完成后自动评分,量化 AI 编码质量;deterministic 证据链可审计。</td>
|
|
85
81
|
</tr>
|
|
86
82
|
</table>
|
|
@@ -91,26 +87,38 @@ Forge 是 deterministic 的——范围是 "deterministic where code can verify"
|
|
|
91
87
|
|
|
92
88
|
```bash
|
|
93
89
|
cd your-project
|
|
94
|
-
forge init
|
|
95
|
-
# 回到 Claude Code 继续工作:AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程
|
|
90
|
+
forge init # 在仓库里声明契约:只写仓库内产物
|
|
96
91
|
```
|
|
97
92
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
`forge init` **不在项目目录写任何文件**(不会被 git add 误提交),全部资产落在用户级:
|
|
93
|
+
`forge init` **只在仓库里写文件**(随 git 提交,不会被误当成用户级状态):
|
|
101
94
|
|
|
102
95
|
| 路径 | 说明 |
|
|
103
96
|
|------|------|
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
| `~/.claude/skills/forge-quality/` | 质量协议 Skill |
|
|
109
|
-
| `~/.codex/hooks.json`、`~/.cursor/hooks.json` 等 | 其他 agent 的用户级 hook 接线(按检测到的工具) |
|
|
97
|
+
| `spec/forge.yaml` | 仓库契约(`version: "1"`、`profile`、`hooks: off` 兼容字段) |
|
|
98
|
+
| `spec/changes/` | change 产物目录(含 `archive/`) |
|
|
99
|
+
| `AGENTS.md` | forge 托管块(可提交共享给协作者与 agent) |
|
|
100
|
+
| `CLAUDE.md`、`.cursor/rules/forge.mdc` | 只在文件/目录已存在时追加/补齐指针 |
|
|
110
101
|
|
|
111
|
-
|
|
102
|
+
它**不写** `~/.forge`、`~/.claude`、`~/.codex`,也不登记全局注册表;重复运行只同步仓库内托管块。`--project` 已废弃为 no-op,`--profile mini|standard|full` 写入契约。
|
|
112
103
|
|
|
113
|
-
|
|
104
|
+
forge **没有宿主层**:不分发宿主插件、不写宿主配置。门禁由 agent 显式跑 `forge task`/`forge change` 命令驱动;证据、状态与判据仍然落盘、可审计。需要全局看板或 `forge task list --open --all-projects` 时,用 `forge registry add` 显式登记项目(`forge dashboard` 只读聚合登记过的项目)。
|
|
105
|
+
|
|
106
|
+
> **仓库自己决定要不要接管。** `forge init` 写的 `spec/forge.yaml` 把成员资格放在仓库本身——clone 到新机器、换个 agent 也能解析到项目身份。
|
|
107
|
+
>
|
|
108
|
+
> 查找位置:**只认 git 仓库根的 `spec/forge.yaml`**,向上找到 git 根就停;子目录里的同名文件不激活整仓(monorepo 里一个子包不该悄悄改变别人的行为,要激活就放到仓库根),非 git 目录向上查找,走到用户 home 就停(`~` 本身不算项目根)。放好之后 `forge status` 应显示 `spec: spec/forge.yaml (仓库声明式成员资格)`;`forge policy state` 应输出 managed(declined 的仓库例外——`forge off`、`policy yield` 或 clone 到带 `.forge-decline` 的仓库都会这样;成员资格退出优先于契约,`forge on` 可恢复)。
|
|
109
|
+
|
|
110
|
+
```yaml
|
|
111
|
+
# spec/forge.yaml
|
|
112
|
+
version: "1" # 契约版本,按主版本兼容
|
|
113
|
+
profile: standard # standard | mini | full(省略该字段按 standard 解析;forge init 写入的是 mini)
|
|
114
|
+
hooks: off # 兼容字段:保留只为老契约可解析,不启用任何执法
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
- `profile` 决定任务门禁的严格档位(`mini` 最小集、`standard` 缺省、`full` 预留超集位)。
|
|
118
|
+
- 契约写坏时按最小档静默降级——`forge status` 会提示「⚠ 契约无法解析」但不阻断任何命令。
|
|
119
|
+
- `forge change init` 生成的是最小契约(`version: "1"`、`profile: mini`)。`--profile` 只改契约档位。
|
|
120
|
+
|
|
121
|
+
> **团队要 git 共享同一份协议?** 提交 `spec/` 与 `AGENTS.md` 即可:契约、change 产物与托管块都随仓库走,协作者 clone 后 `forge status` 就按仓库契约解析。
|
|
114
122
|
|
|
115
123
|
## 📋 命令速查
|
|
116
124
|
|
|
@@ -118,8 +126,9 @@ forge init # 默认零项目写入,全部资产落在用户级
|
|
|
118
126
|
|
|
119
127
|
| 命令 | 用途 |
|
|
120
128
|
|------|------|
|
|
121
|
-
| `forge init` |
|
|
129
|
+
| `forge init` | 在仓库里声明 forge 契约:写 `spec/forge.yaml`、`spec/changes/`、AGENTS.md 托管块,并按默认规则维护已存在的入口指针;不写 `~/.forge`(`--profile mini\|standard\|full`,`--project` 已废弃为 no-op) |
|
|
122
130
|
| `forge next` | 从 git/任务状态推导**恰好一条**下一步命令——agent 不自选下一步 |
|
|
131
|
+
| `forge change init/new/list/verify/status/gate/check/agents` | 仓库内 change 生命周期:`spec/changes/<id>/` 四份产物(proposal/design/tasks/acceptance)+ 可执行判据 + 证据封印(绑定 commit;工作区有未提交改动时另记每个文件的 sha256——不依赖 forge 接管,产物随仓库走)。`status` 是循环里唯一该看的下一步来源(同因失败 3 次就停下交给人;`prior_attempts` 列出最近失败的证据,返工前先读);`gate --task N` 只跑某条任务的判据;`check` 是 CI 与 pre-commit 共用的证据闸门(未封印/失效/失败 → 退出 2,`--staged` 只查暂存区碰到的 change);`agents` 重同步 AGENTS.md 的 forge 托管块并维护 `CLAUDE.md` / `.cursor/rules/forge.mdc` 指针(有块只改块内、无块末尾追加;`CLAUDE.md` 不存在默认不建,`.cursor/rules/` 目录已存在时补 forge.mdc,要凭空创建用 `--pointers`,`none` 完全不碰);`change init` 会在仓库根写 `spec/` 与 AGENTS.md,并按默认规则维护已存在的入口指针(已有 `CLAUDE.md` 追加指针、已有 `.cursor/rules/` 目录补 `forge.mdc`;随 git 提交;与 `forge init` 同源,都是仓库内产物);`new --fast` 只要求 proposal + acceptance |
|
|
123
132
|
| `forge task start --ref <type/desc> --branch --accept "run :: expected"` | 建任务 + 建分支 + 登记验收标准 |
|
|
124
133
|
| `forge task gate <gate-id>` | 推进门禁:task-implement → task-verify → task-complete |
|
|
125
134
|
| `forge task verify-acceptance` | 实跑验收标准,落 deterministic 证据 |
|
|
@@ -128,32 +137,21 @@ forge init # 默认零项目写入,全部资产落在用户级
|
|
|
128
137
|
| `forge task resume --match "<关键词>"` | 跨会话/跨工具拉回任务上下文 |
|
|
129
138
|
| `forge review pass` / `forge review status` | 代码审查标记与状态 |
|
|
130
139
|
| `forge gate push` | git 推送边界门禁(cheat-scan 复检 + 未消解 BLOCKED 任务) |
|
|
131
|
-
| `forge hazard confirm --last` | 确认最近一条被拦高危命令(须真人终端) |
|
|
132
|
-
| `forge freeze <路径>...` | 冻结写入范围,冻结路径之外的写全部硬阻断 |
|
|
133
140
|
| `forge trace <ref>` / `forge health` / `forge dashboard` | 证据链时间线 / 质量趋势 / 全局看板(Pulse) |
|
|
134
|
-
| `forge
|
|
141
|
+
| `forge status` | 项目状态 |
|
|
135
142
|
|
|
136
|
-
其余命令族(`skills`、`eval`、`act`、`workspace`、`project`、`registry
|
|
143
|
+
其余命令族(`skills`、`enforcement`、`eval`、`act`、`workspace`、`project`、`registry`(含 `registry add` 显式登记)、`harness`、`compat`、`conventions`、`policy`、`selfcheck`、`migrate`、`update`、`node`、`bridge`、`docs`、`worktree`、`on`/`off`、`config`、`verify`、`trust`)见同一份[完整命令表](docs/reference/cli.md)。
|
|
137
144
|
|
|
138
|
-
|
|
145
|
+
**回环怎么跑**:agent 每个回合先 `forge change status <id>`,只执行它给出的下一步——补产物、跑 verify、读失败证据、重跑,acceptance 的判据全部通过才归档。判断标准来自仓库里的文件与证据,不来自对话记忆;in-loop 不需要宿主插件(`forge change status/verify` 仍是 forge 二进制提供的命令,所以「零安装」指不用装宿主插件,不是不用装 forge)。逐节点推进用 `forge change gate <id> --task N`:只跑该任务引用的判据,节点证据不封印整条 change。
|
|
139
146
|
|
|
140
|
-
|
|
147
|
+
**证据怎么变成合并前提**:`forge change check` 给 CI 与 pre-commit 同一套判据——每个未归档 change 都得有一份与当前代码和判据一致的封印证据。仓库里带两份接线示例:
|
|
141
148
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
├─ task-guard: Write/Edit → 检查任务状态 + 自保护(forge 配置层)
|
|
145
|
-
└─ bash-guard: Bash → 检测写文件模式
|
|
149
|
+
- `.githooks/pre-commit`:`git config core.hooksPath .githooks` 启用。它只查暂存区碰到的 change;一旦暂存区出现 `spec/changes/` 之外的改动(代码、文档),就退化为检查全部 change——封印的证据绑的是代码内容,只看被碰到的 change 会放行一个注定在 CI 变红的提交。hook 执行时看的是工作区:`git add` 后又改回文件、或漏 add 证据,本地可能放行而 CI 变红。机器上没有 `forge` 或版本太旧时它打印原因后放行,仓库还没有 `spec/changes/` 时静默放行(不打扰还没用 change 流程的仓库);POSIX 上需要可执行位,clone 后若丢了用 `chmod +x .githooks/pre-commit`。
|
|
150
|
+
- `.github/workflows/change-verify.yml`:只在 PR 上跑(main 上有新提交后再 merge,合并后的树与被封印的那版不同,证据按设计判失效——那是合并噪音,不是代码变了),`fetch-depth: 0` 且检 PR head sha;有 `spec/changes/` 才执行 `forge change check`,没有就整步跳过。它从源码构建 forge(这一行只在 forge 自己的仓库成立;别的仓库要换成安装固定版本的 forge),所以不存在「没装 forge 就放行」;要让它在 GitHub 上真拦住合并,还得在仓库设置里设为 required status check。
|
|
146
151
|
|
|
147
|
-
|
|
148
|
-
└─ file-sentinel: Bash → 对比执行前后 git 状态,未授权变更隔离到 DataDir/quarantine/(可恢复)
|
|
152
|
+
`--json` 在所有路径上输出同一份 `{checked,problems,skipped}`(空列表是 `[]`,跳过时退出码 0)。信任边界:`change check` 只把未归档 change 当作待交付物,已归档的是历史;把未封印的 change 手工 `git mv` 进 `archive/` 等于人宣布它已交付——工具不再检查,这一步只能靠 review。
|
|
149
153
|
|
|
150
|
-
|
|
151
|
-
└─ task-verify: 检查任务完成度 + 主分支保护 + 自身版本
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
活跃任务内,Agent 无法通过 `node -e "fs.writeFileSync()"`、`cat > file`、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层,file-sentinel 监控文件层,task-guard 保护配置层。**没有活跃任务时 task-guard 只给 WARN 提示,不是硬墙**;有任务才按门禁语义拦截。
|
|
155
|
-
|
|
156
|
-
27 个内置 Hook 的完整清单(触发时机、职责;可关闭的门禁类都附了逃生开关)见 [docs/reference/hooks.md](docs/reference/hooks.md)。
|
|
154
|
+
「同一个原因」指每次 verify/gate 的**第一条失败命令**:换一条命令、或中间有一次通过,就重新计数。连续 3 次同因失败 → `blocked`,此时 `next_steps` 不再给任何可执行命令,恢复命令放在 `handoff` 字段里,由人执行。fast change(`new --fast`)的判据与证据规则和普通 change 完全一样,只是只要求 proposal + acceptance 两份产物。
|
|
157
155
|
|
|
158
156
|
## 📦 安装
|
|
159
157
|
|
|
@@ -167,22 +165,6 @@ npm install -g @agent_forge/forge
|
|
|
167
165
|
# 支持平台:macOS (x86_64/ARM64)、Linux (x86_64/ARM64)、Windows (x86_64)
|
|
168
166
|
```
|
|
169
167
|
|
|
170
|
-
> 「plugin」在 Forge 语境指**宿主接线打包**(分发层,`plugins/forge` / `plugins/forge-dsh`),与 dsh/Cordis 的运行时插件同名不同物——辨析见 [plugin-philosophy.md](docs/design/plugin-philosophy.md)。
|
|
171
|
-
|
|
172
|
-
<details>
|
|
173
|
-
<summary><b>📖 通过 Claude Code plugin marketplace(用户级,一次性接线)</b></summary>
|
|
174
|
-
|
|
175
|
-
若主要用 Claude Code,可走 plugin marketplace 一次性接线用户级 hooks(机器上所有项目共享,连 `~/.claude/settings.json` 都不用动):
|
|
176
|
-
|
|
177
|
-
```
|
|
178
|
-
/plugin marketplace add MjxUpUp/Forge
|
|
179
|
-
/plugin install forge@forge
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
仍需 `npm install -g @agent_forge/forge` 装二进制(hooks 都 spawn forge)。项目登记按 takeover 偏好(出厂默认 **ask**):init-suggest SessionStart hook 在未接管项目首次会话**询问一次**(同意→`forge init`;拒绝→`forge off`);要"装好即用"的无感体验→`forge config set` takeover 为 auto(静默接管所有 git 项目;declined、`.forge-decline` 团队声明与外来 harness 让位仍然生效)。hooks 由 plugin.json 全机器接管,`forge init` 跳过自己的 settings.json 注册。完整三步与各 host 差异见 `plugins/forge/README.md`。
|
|
183
|
-
|
|
184
|
-
</details>
|
|
185
|
-
|
|
186
168
|
## 🤝 贡献
|
|
187
169
|
|
|
188
170
|
欢迎提 Issue 和 PR。开发时注意:
|
|
@@ -194,17 +176,15 @@ npm install -g @agent_forge/forge
|
|
|
194
176
|
缺文件整包测试直接红,必须入库;`docs/design/` 属设计文档,同样随代码提交);排除
|
|
195
177
|
`.claude/`、`.forge/` 等生成物与临时工作目录。
|
|
196
178
|
|
|
197
|
-
|
|
179
|
+
详见仓库内的 `AGENTS.md` 托管块(`forge init` 写入,随 git 共享给协作者与 agent)。
|
|
198
180
|
|
|
199
181
|
## 📚 更多文档
|
|
200
182
|
|
|
201
183
|
| 文档 | 说明 |
|
|
202
184
|
|------|------|
|
|
203
185
|
| [完整命令参考](docs/reference/cli.md) | 每个命令、flag、逃生舱与门禁语义 |
|
|
204
|
-
| [Hook 完整清单](docs/reference/hooks.md) | 27 个内置 Hook 的触发时机与职责 |
|
|
205
186
|
| [定位与设计依据](docs/design/positioning.md) | 为什么是确定性门禁而不是模型自检 |
|
|
206
187
|
| [中文使用指南](READMEs/README.zh-CN.md) | 面向国内用户的安装 / 日常 / 多宿主精简指南 |
|
|
207
|
-
| [Plugin 安装详解](plugins/forge/README.md) | 多 host plugin marketplace 三步接线与各 host 差异 |
|
|
208
188
|
| [项目主页](homepage/index.md) | 一分钟简介 + 核心能力速览 |
|
|
209
189
|
| [评估数据约定](evals/README.md) | skill eval 黄金 case 集与盲测迭代纪律 |
|
|
210
190
|
|
package/bin/forge
CHANGED
|
Binary file
|
package/package.json
CHANGED