@agent_forge/forge-win32-x64 1.15.1
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/LICENSE +201 -0
- package/bin/README.md +362 -0
- package/bin/forge.exe +0 -0
- package/package.json +16 -0
package/bin/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 MjxUpUp
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/bin/README.md
ADDED
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
<a id="top"></a>
|
|
2
|
+
<div align="center">
|
|
3
|
+
|
|
4
|
+
# 🔥 Forge
|
|
5
|
+
|
|
6
|
+
**AI 开发质量门禁引擎**
|
|
7
|
+
|
|
8
|
+
Stop trusting AI-generated code. Start gating it.
|
|
9
|
+
|
|
10
|
+
[](https://github.com/MjxUpUp/Forge/actions/workflows/ci.yml)
|
|
11
|
+
[](https://www.npmjs.com/package/@agent_forge/forge)
|
|
12
|
+
[](https://www.npmjs.com/package/@agent_forge/forge)
|
|
13
|
+
[](https://go.dev)
|
|
14
|
+
[](#-安装)
|
|
15
|
+
[](#license)
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
<div align="center">
|
|
20
|
+
<img src="dashboard-render.png" alt="Forge Dashboard 质量看板" width="860"/>
|
|
21
|
+
<p><sub>Forge Dashboard —— 项目级质量趋势可视化（分数走势 / 证据盲区率 / 复发低分维度）</sub></p>
|
|
22
|
+
</div>
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
<details>
|
|
27
|
+
<summary><b>📖 目录</b></summary>
|
|
28
|
+
|
|
29
|
+
- [核心功能](#-核心功能)
|
|
30
|
+
- [快速开始](#-快速开始)
|
|
31
|
+
- [它如何工作](#-它如何工作)
|
|
32
|
+
- [定位：Loop Engineering 的验证 / 状态层](#-定位loop-engineering-的验证--状态层)
|
|
33
|
+
- [工作流程](#-工作流程)
|
|
34
|
+
- [Hook 系统](#-hook-系统)
|
|
35
|
+
- [命令参考](#-命令参考)
|
|
36
|
+
- [安装](#-安装)
|
|
37
|
+
- [贡献](#-贡献)
|
|
38
|
+
- [更多文档](#-更多文档)
|
|
39
|
+
- [License](#license)
|
|
40
|
+
|
|
41
|
+
</details>
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
> **AI 写的代码，你放心直接提交吗？**
|
|
46
|
+
|
|
47
|
+
Forge 在 AI 编码过程中自动插入结构化质量门禁——从任务创建到代码提交，确保每一步产出物都经过验证。配合 Claude Code 的 Hook 系统实现实时拦截，不需要你手动检查。
|
|
48
|
+
|
|
49
|
+
## ✨ 核心功能
|
|
50
|
+
|
|
51
|
+
<table>
|
|
52
|
+
<tr>
|
|
53
|
+
<td width="50%" valign="top"><strong>🚦 任务级门禁</strong><br/>每个开发任务走 3 道门禁：实现 → 验证 → 完成，门禁之间有活动检查防止跳阶段。</td>
|
|
54
|
+
<td width="50%" valign="top"><strong>🪝 实时 Hook 拦截</strong><br/>多个内置 Hook，在 AI 写代码的同时自动检查质量、防止绕过（读改前置 / 文件监控 / 高危拦截）。</td>
|
|
55
|
+
</tr>
|
|
56
|
+
<tr>
|
|
57
|
+
<td valign="top"><strong>🛡️ 安全纵深防御</strong><br/>三层防御架构：工具拦截 → 文件监控 → 自身保护。Agent 无法经 bash 绕道篡改。</td>
|
|
58
|
+
<td valign="top"><strong>📊 质量评分</strong><br/>每个任务完成后自动评分，量化 AI 编码质量；deterministic 证据链可审计。</td>
|
|
59
|
+
</tr>
|
|
60
|
+
</table>
|
|
61
|
+
|
|
62
|
+
## 🚀 快速开始
|
|
63
|
+
|
|
64
|
+
需要 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 已安装。
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# 安装
|
|
68
|
+
npm install -g @agent_forge/forge
|
|
69
|
+
|
|
70
|
+
# 在项目目录初始化
|
|
71
|
+
cd your-project
|
|
72
|
+
forge init
|
|
73
|
+
|
|
74
|
+
# 在 Claude Code 中开始工作
|
|
75
|
+
# AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
初始化后 Forge 会创建：
|
|
79
|
+
|
|
80
|
+
| 路径 | 说明 |
|
|
81
|
+
|------|------|
|
|
82
|
+
| `.forge/` | Hook 脚本、任务状态、协议配置 |
|
|
83
|
+
| `.claude/settings.local.json` | Hook 集成配置 |
|
|
84
|
+
| `.claude/CLAUDE.md` | 质量协议引用 |
|
|
85
|
+
| `.claude/skills/` | 质量协议 Skill |
|
|
86
|
+
|
|
87
|
+
> **主要用 Claude Code？** 走 [plugin marketplace](plugins/forge/README.md) 一次性接线用户级 hooks（机器上所有项目共享，无需逐项目配 `.claude/settings.local.json`）。
|
|
88
|
+
|
|
89
|
+
## 🔧 它如何工作
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
┌──────────────────────────────────────────────────┐
|
|
93
|
+
│ coding agent │
|
|
94
|
+
│ (Claude Code / Codex / Cursor ...) │
|
|
95
|
+
└────────────────────┬─────────────────────────────┘
|
|
96
|
+
│ 每次 Write / Edit / Bash
|
|
97
|
+
▼
|
|
98
|
+
┌──────────────────────────────────────────────────┐
|
|
99
|
+
│ Forge Hooks · 实时拦截 │
|
|
100
|
+
│ task-guard · read-before-edit · bash-guard │
|
|
101
|
+
│ hazard-guard · file-sentinel · cheat-scan │
|
|
102
|
+
└────────────────────┬─────────────────────────────┘
|
|
103
|
+
│
|
|
104
|
+
▼
|
|
105
|
+
┌──────────────────────────────────────────────────┐
|
|
106
|
+
│ 任务门禁 · 持久化状态 │
|
|
107
|
+
│ task-implement → task-verify → task-complete │
|
|
108
|
+
└────────────────────┬─────────────────────────────┘
|
|
109
|
+
│
|
|
110
|
+
▼
|
|
111
|
+
📊 质量评分 + deterministic 证据链
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
每轮 AI 编码循环都被门禁兜底：编译是否通过、断言有没有被弱化、改代码前是否真读过、文件有没有被绕道篡改——循环跑得越快，越需要自动化验证，而不是靠人盯着。
|
|
115
|
+
|
|
116
|
+
## 🎯 定位：Loop Engineering 的验证 / 状态层
|
|
117
|
+
|
|
118
|
+
AI 编码是一个循环：写代码 → 运行 → 读反馈 → 修正 → 再写。这个循环由 coding agent（Claude Code、Codex）驱动，**Forge 不替代循环本身**——它补上循环最容易缺的两层：
|
|
119
|
+
|
|
120
|
+
- **验证层** — 每一轮产出物经门禁检验：编译通过、断言没被弱化、改代码前确实读过代码、文件未被绕道篡改。循环跑得越快，越需要自动化验证兜底，而不是靠人盯着。
|
|
121
|
+
- **状态层** — 跨循环的任务状态：3 道门禁（实现 → 验证 → 完成）、活跃任务追踪、门禁历史。"做到哪了 / 是否达标"有持久化、可审计的记录，而不是只活在 agent 的上下文里（上下文一压缩就丢）。
|
|
122
|
+
|
|
123
|
+
换言之，coding agent 负责**跑循环**，Forge 负责**让每一轮循环产出可信、状态可追**。Forge 不 discovery、不规划需求——那些是循环前端的事；Forge 守的是循环的执行质量。
|
|
124
|
+
|
|
125
|
+
## 🔧 工作流程
|
|
126
|
+
|
|
127
|
+
每个开发任务自动走 3 道门禁：
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
forge task start --ref feat/add-login --branch --accept "go test ./... :: PASS" # 创建任务+分支+登记验收标准（--accept 可重复）
|
|
131
|
+
forge task start --ref feat/add-login --scope "internal/auth/*.go" # 声明计划改动白名单（规划前置→可度量契约，advisory 检测 scope-drift）
|
|
132
|
+
# AI 自动完成工作...
|
|
133
|
+
forge task gate task-implement # ✅ 代码实现（advisory：编译/断言提醒，agent 自检）
|
|
134
|
+
forge task verify-acceptance # ✅ 实跑验收标准，记 deterministic 证据（spec-as-gate）
|
|
135
|
+
forge task gate task-verify # ✅ 测试验证
|
|
136
|
+
forge task scope show # 查看声明白名单 + 实时 scope-drift（advisory，不阻塞）
|
|
137
|
+
forge task gate task-complete # ✅ 完成确认
|
|
138
|
+
forge task score # 查看质量评分
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
<details>
|
|
142
|
+
<summary><b>📖 门禁细节：退出码契约 / PlanScope / Cheat-scan</b></summary>
|
|
143
|
+
|
|
144
|
+
门禁之间有时间和活动检查，防止 AI 跳过阶段直接提交。`task-implement` 的编译/断言检查为 advisory 提醒（由 agent 自检，不阻塞）——forge 技术栈无关，适配 loop engineering。`forge task verify-acceptance` 实跑 `task start --accept` 登记的验收标准（`Run :: Expected`），把 dev-workflow Plan 的验收条件从 plan 文本变成不可伪造的 deterministic 证据——对冲 agent 自述"满足验收"却没真跑的盲区。
|
|
145
|
+
|
|
146
|
+
**门禁退出码契约**：`forge task gate` 非 0 退出（输出 `BLOCKED:` 前缀）= 硬阻断，必须修复后重跑；零退出但见 `ADVISORY:` 前缀 = 软信号（gate 仍过、已记 checklog，应修不阻断）。按退出码而非文案行动——硬错误的散文易被误读成提醒而跳过。
|
|
147
|
+
|
|
148
|
+
**PlanScope 白名单（规划前置）**：`task start --scope <glob>`（可重复，或中途 `forge task scope add <glob>` 追加）声明"打算改哪些文件"。`task-verify` 比对实改源码与声明的差集，记一条 `scope-drift` 证据（deterministic，`forge trace` 可见）并 stderr 提醒。全程 **advisory 不阻塞**——变更影响分析召回率仅 ~44%，scope 是 prediction 非 contract，偏差是常态信号而非异常；它把"规划前置"变成可度量、可回顾的契约，正堵在 review 反复出问题的根因上。
|
|
149
|
+
|
|
150
|
+
**Cheat-scan（机械作弊模式扫描）**：`task-verify` 扫任务新增行（`+` 行），机械检测 4 类 AI 作弊模式——`type-suppression`（`@ts-ignore`/`eslint-disable`/`#[allow]`/`type: ignore`）、`error-swallow`（空 `catch{}`/`except:pass`）、`dead-branch`（`if(false)`/`if(1===2)`）、`comment-only-fix`（某文件新增行全注释零逻辑）——记一条 `cheat-scan` 证据（deterministic，`forge trace` 可见）并 stderr 列出命中。全程 **advisory 不阻塞**：这些模式此前全靠 code-review-gate 的 LLM 子 agent 判断，LLM 每轮对同一 diff 重新采样抓不同子集，是"每轮 review 冒新问题"的体感来源；抽到 deterministic 后，机械模式一次判准，LLM-reviewer 退到只做语义判断（设计/架构/mock 是否幻觉）。`comment-only-fix` 是启发式（severity=low，纯文档任务可能误报）。
|
|
151
|
+
|
|
152
|
+
</details>
|
|
153
|
+
|
|
154
|
+
## 🪝 Hook 系统
|
|
155
|
+
|
|
156
|
+
Forge 通过 Claude Code 的 Hook 机制实现实时质量检查。三层纵深防御，监控的是文件而非工具：
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
Layer 1: PreToolUse 快速拦截
|
|
160
|
+
├─ task-guard: Write/Edit → 检查任务状态 + 保护 .forge/*
|
|
161
|
+
└─ bash-guard: Bash → 检测写文件模式
|
|
162
|
+
|
|
163
|
+
Layer 2: PostToolUse 文件监控
|
|
164
|
+
└─ file-sentinel: Bash → 对比执行前后 git 状态，未授权变更自动 revert
|
|
165
|
+
|
|
166
|
+
Layer 3: 会话结束验证
|
|
167
|
+
└─ task-verify: 检查任务完成度 + 主分支保护 + 自身版本
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Agent 无法通过 `node -e "fs.writeFileSync()"`、`cat > file`、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层，file-sentinel 监控文件层，task-guard 保护配置层。
|
|
171
|
+
|
|
172
|
+
<details>
|
|
173
|
+
<summary><b>📖 内置 Hook 完整清单（17 个）</b></summary>
|
|
174
|
+
|
|
175
|
+
| Hook | 触发时机 | 功能 |
|
|
176
|
+
|------|----------|------|
|
|
177
|
+
| **task-guard** | Write/Edit 前 | 无活跃任务时 WARN（仅 `.forge/*` 自保护文件 FAIL），保护 Forge 配置不被篡改 |
|
|
178
|
+
| **read-before-edit** | Write/Edit 前（活跃任务内） | 编辑本会话未 Read 过的现存源文件 → 硬阻断（`BLOCKED`）。Edit 需精确匹配旧文本，未读即凭记忆盲改——old_string 撞中即错改入库，先 Read 再 Edit。豁免新建文件/测试文件/非源码；批量重构逃生 `forge task override --work-activity disable`（降 evidence 强度到 Weak）。reads-log 落盘随会话存活，压缩后仍累计 |
|
|
179
|
+
| **assertion-check** | Write/Edit 前 | 检测断言弱化（t.Fatal → t.Log、assert! 被删除等），advisory 提醒不阻塞（agent 自检） |
|
|
180
|
+
| **bash-guard** | Bash 前 | 检测命令中的写文件模式（writeFile、cat >、sed -i 等），无任务时 WARN（源码随后被 file-sentinel 隔离） |
|
|
181
|
+
| **hazard-guard** | Bash 前 | 高危命令（`rm -rf`、`git push --force`、`DROP TABLE/SCHEMA`、`TRUNCATE`、`GRANT ALL`、`kubectl delete`、`docker system prune`、无 WHERE 的 `DELETE/UPDATE` 等）human-in-the-loop 拦截：block + 指引用户确认 → `forge hazard confirm` 登记 5min 限时标记 → 重试放行；测试/CI 设 `FORGE_ALLOW_HAZARD=1` 跳过 |
|
|
182
|
+
| **auto-compile** | Write/Edit 后 | advisory 提醒用对应技术栈编译命令自检（go build / cargo check / mvn / tsc 等），不强制编译 |
|
|
183
|
+
| **workflow-test-guard** | Write/Edit 后 | 改 `.github/workflows/*.yml` 后自动跑 `internal/ci` 守护测试，把"沙盒异常"即时反馈给 agent（不依赖 CI 兜底），是 release.yml test→goreleaser→npm needs 链的实时守护层 |
|
|
184
|
+
| **file-sentinel** | Bash 后 | 监控文件变更，未授权修改隔离到 DataDir/quarantine/（`forge data-dir` 查看路径，可恢复，不删除） |
|
|
185
|
+
| **tool-track** | Read 后 | 静默记录 Read 调用到 toollog，供 task-verify 的 read-before-edit 门禁判断（agent 是否先读代码再改） |
|
|
186
|
+
| **task-verify** | 会话结束 | advisory：任务门禁/主分支保护到 stderr+checklog（不阻塞会话结束） |
|
|
187
|
+
| **review-stop** | 会话结束 | code-review-gate 自动挡：未审源码变更 block 会话结束。task 模式不重复拦（task-complete 门禁 ReviewPassed 硬前置已强制），非 task 模式按 diff stamp 决策；并发会话检测——其他 session 有活跃任务时放行（调研 session 不被拦） |
|
|
188
|
+
| **skill-scan** | 会话开始 | advisory：扫描 ~/.claude/skills 安全性（forge audit 19 规则），补 install 门控缺口（手动 clone/junction/git pull 进入的 skill），全局 hook 不依赖 forge project |
|
|
189
|
+
| **mcp-scan** | 会话开始 | advisory：扫描项目级 `.mcp.json` 的 server 配置（管道执行/任意包执行 npx·uvx·dlx·bunx/内联代码/非 https URL/env 明文凭证），补 skill-scan 盲区（攻击者可经 PR 植入恶意 server，clone 即自动连接）；只审 config 层，runtime tool description 注入（Tool Poisoning）不在能力内，全局 hook |
|
|
190
|
+
| **init-suggest** | 会话开始 | advisory：检测 git 项目无 `.forge/` 时，首次提示 agent 询问是否启用 forge（用户拒绝→`forge suggest decline` 永久静默；设 `FORGE_AUTO_INIT=1` 处处自动 init，注意 `forge init` 会写入 `.forge/`、`CLAUDE.md`/`AGENTS.md`、`.claude/settings.local.json`、skills——会对所在项目产生文件变更），全局 hook，补"每项目手动 init"缺口，实现一次安装后项目级资产自动就位 |
|
|
191
|
+
| **task-resume** | 会话开始 | advisory：自动注入活跃任务的接续上下文（目标/计划/决策/阻塞/门禁进度/git 已改未提交）+ 锚定当前 session——接手方冷启动即知任务在哪一步，无需手动 forge task resume；无活跃任务静默；项目级 hook |
|
|
192
|
+
| **compact-resume** | 压缩后（claude-code only） | PostCompact 时设 `ResumeStale=true` 标志（PostCompact 不在 additionalContext 注入点，只设标志等下个 prompt 重注入），context-rot 抗机制根治层·设标志半边 |
|
|
193
|
+
| **resume-reinject** | 用户提交时（claude-code only） | 检测 `ResumeStale=true`（刚压缩过）→ 输出完整接续上下文并清标志。补 task-resume 缺口（SessionStart 只注入一次，会话中途压缩不补），context-rot 抗机制根治层·重注入半边 |
|
|
194
|
+
|
|
195
|
+
</details>
|
|
196
|
+
|
|
197
|
+
## 📋 命令参考
|
|
198
|
+
|
|
199
|
+
<details>
|
|
200
|
+
<summary><b>🔧 项目管理</b></summary>
|
|
201
|
+
|
|
202
|
+
| 命令 | 说明 |
|
|
203
|
+
|------|------|
|
|
204
|
+
| `forge init` | 初始化项目（生成 `.forge/` 资产、Hook、质量协议 Skill；旧的 `--mode` 标志已废弃为 no-op） |
|
|
205
|
+
| `forge status [--json]` | 查看项目状态（任务管道 + 质量信号） |
|
|
206
|
+
| `forge verify` | 项目完整性检查 + 回归测试 |
|
|
207
|
+
| `forge update [--plugin]` | 自更新到最新版本；加 `--plugin` 在 binary 更新后打印 plugin marketplace 重装指引（marketplace 镜像同步 hook 时建议重装） |
|
|
208
|
+
| `forge suggest decline/status/reset` | 管理 init-suggest hook 的项目 init 提示状态（decline 永久静默当前项目 / status 查看 / reset 清除重新提示） |
|
|
209
|
+
| `forge uninstall` | 一键反装：清 npm global `@agent_forge/forge` + 删 init-suggest 标记（默认 `~/.forge/.init-suggested/`，设 `FORGE_DATA_HOME` 时落该根下）；plugin 卸载须在 agent CLI 内交互运行（不可脚本化） |
|
|
210
|
+
| `forge migrate [--dry-run] [--force]` | 把旧 `.forge/` runtime state（tasks/gates/checklog/toollog/act/sessions/quarantine/active-task-ref 等）迁到用户级 DataDir（`~/.forge/projects/<key>/`）——升级到 runtime state 外迁版本后的迁移路径；项目配置（hooks/protocol.yml 等）不迁仍留 `.forge/`；幂等，`--dry-run` 预览，`--force` 覆盖 DataDir 已有同名 |
|
|
211
|
+
| `forge registry prune` | 精简全局注册表 `~/.forge/projects.json`——移除 `.forge/` 不存在的死路径与重复条目（项目移走/删除/测试残留），原子写回。registry.List 读时惰性精简但只在 `forge dashboard --global` 触发（启 web 阻塞），本命令给不启 web 的主动清理入口 |
|
|
212
|
+
|
|
213
|
+
</details>
|
|
214
|
+
|
|
215
|
+
<details>
|
|
216
|
+
<summary><b>🚦 任务管理</b></summary>
|
|
217
|
+
|
|
218
|
+
| 命令 | 说明 |
|
|
219
|
+
|------|------|
|
|
220
|
+
| `forge task start --ref <type/desc> --branch` | 创建任务（自动创建分支） |
|
|
221
|
+
| `forge task status` | 查看当前任务门禁状态 |
|
|
222
|
+
| `forge task list` | 列出所有任务 |
|
|
223
|
+
| `forge task gate <gate-id>` | 验证单道任务门禁 |
|
|
224
|
+
| `forge task verify-acceptance` | 实跑验收标准（task start --accept 登记），记 deterministic 证据 |
|
|
225
|
+
| `forge task scope add <glob>` | 追加计划改动文件到白名单（支持中途迭代） |
|
|
226
|
+
| `forge task scope show` | 查看声明的白名单 + 实时 scope-drift（advisory，不阻塞） |
|
|
227
|
+
| `forge task complete` | 标记任务完成（自动评分） |
|
|
228
|
+
| `forge task abort [--ref <ref>]` | 中止并删除任务（清理 ghost/卡住任务，不评分） |
|
|
229
|
+
| `forge task score` | 查看任务质量评分 |
|
|
230
|
+
| `forge task resume [--ref <ref>]` | 拉回任务接续上下文（目标/计划/决策/阻塞/参与工具+门禁进度+git 已改），跨会话/跨工具秒级恢复 |
|
|
231
|
+
| `forge task context [--ref <ref>]` | 只读查看接续上下文（resume 的不改 state 别名） |
|
|
232
|
+
| `forge task decide --content` | 记录已确认决策（持久化进 task，跨会话/跨工具不再推翻） |
|
|
233
|
+
| `forge task next <step>` | 追加下一步（可多条） |
|
|
234
|
+
| `forge task block --content/--resolve <id>` | 登记阻塞或解决阻塞（open→resolved） |
|
|
235
|
+
| `forge task finding --content/--resolve <id>` | 记录跨工具发现（带来源工具）或标 fixed |
|
|
236
|
+
| `forge task attach --ref --tool` | 锚定 session+工具到 task（跨工具多向锚定：pi 起、claude-code 接） |
|
|
237
|
+
|
|
238
|
+
</details>
|
|
239
|
+
|
|
240
|
+
<details>
|
|
241
|
+
<summary><b>🔍 代码审查 / 高危命令 / Act 反馈（自动挡）</b></summary>
|
|
242
|
+
|
|
243
|
+
**代码审查门禁**：`forge review` 让 code-review-gate 从"靠手动唤起"变成自动挡——task 流程下 task-complete 门禁强制 ReviewPassed 前置（提交前必审）；非 task 流程下 Stop hook 自动拦截未审的源码变更。误触发已防护：纯文档/配置/生成物变更、无变更、commit 后干净工作区不触发；同一 diff 反复未审最多 block 3 次后 advisory 放行（防 Stop 死循环）。审查由独立只读子 agent 执行（防自审盲区），见 `code-review-gate` skill。
|
|
244
|
+
|
|
245
|
+
| 命令 | 说明 |
|
|
246
|
+
|------|------|
|
|
247
|
+
| `forge review pass` | 标记当前变更已通过 code-review-gate（task 模式写任务状态，否则写分支 stamp） |
|
|
248
|
+
| `forge review gate` | 判定当前是否需要审查（Stop hook 调用；exit 0=放行，1=需审 block） |
|
|
249
|
+
| `forge review status` | 显示当前审查状态 |
|
|
250
|
+
|
|
251
|
+
**高危命令 human-in-the-loop**：`forge hazard` 让高危命令拦截从 session 级 skill 变成 always-on 自动挡——hazard-guard hook（PreToolUse Bash）检测 `rm -rf` / `git push --force` / `git reset --hard` / `DROP DATABASE|TABLE|SCHEMA` / `TRUNCATE` / `GRANT ALL` / `kubectl delete` / `docker system prune` / `shred` / 无 WHERE 的 `DELETE|UPDATE` 等 → block 并指引 agent 获用户明确确认 → `forge hazard confirm` 登记 5min 限时标记 → 重试放行。HITL 而非硬 block：合法高危操作（删 build 产物）确认后能继续；测试/CI 可设 `FORGE_ALLOW_HAZARD=1` 跳过。
|
|
252
|
+
|
|
253
|
+
| 命令 | 说明 |
|
|
254
|
+
|------|------|
|
|
255
|
+
| `forge hazard confirm <命令>` | 登记一次高危命令确认（5min 内同命令重试放行） |
|
|
256
|
+
| `forge hazard status` | 列出当前有效确认及剩余时间 |
|
|
257
|
+
|
|
258
|
+
**Act 反馈臂（证据驱动结论）**：`forge task complete` 时把本任务的证据驱动结论（评分 + 证据强度 + 验收通过率 + 低分维度）落盘到 `~/.forge/projects/<项目key>/act/conclusions.jsonl`，喂给 `session-retrospective`。证据弱（Unverified/Weak）或低分（<70）的结论标 RetrospectiveNudge——对冲"高分但没真验证"的 LLM-judge 盲区。
|
|
259
|
+
|
|
260
|
+
| 命令 | 说明 |
|
|
261
|
+
|------|------|
|
|
262
|
+
| `forge act show [--ref <ref>]` | 查看最新（或指定）任务结论（含 skill 触达画像——该 task 期间触发了哪些 skill） |
|
|
263
|
+
| `forge act list [--json]` | 列出所有任务结论 |
|
|
264
|
+
| `forge act nudge` | 最新结论有回顾 nudge 时输出一行（否则静默）——供 task-verify 会话结束 hook 消费 |
|
|
265
|
+
|
|
266
|
+
</details>
|
|
267
|
+
|
|
268
|
+
<details>
|
|
269
|
+
<summary><b>🧠 Skill 治理</b></summary>
|
|
270
|
+
|
|
271
|
+
分发内置 canonical skill 库到各 coding agent，并守护 skill 质量（规范 + 安全）。
|
|
272
|
+
|
|
273
|
+
| 命令 | 说明 |
|
|
274
|
+
|------|------|
|
|
275
|
+
| `forge skills install` | 分发 skill 到全局/项目目标目录（link/copy） |
|
|
276
|
+
| `forge skills list` | 列出 canonical skill 库中的 skill |
|
|
277
|
+
| `forge skills audit` | 19 条安全规则审查（prompt 注入/数据外发/危险代码） |
|
|
278
|
+
| `forge skills drift-check` | 检测分发分叉（dry-run，不写） |
|
|
279
|
+
| `forge skills validate` | R1-R9 规范校验 |
|
|
280
|
+
| `forge skills adapters` | 部署 skill-routing adapter（pi/claude/cursor/routes.json） |
|
|
281
|
+
| `forge skills usage` | 使用度量分析（热门 skill + undertrigger 候选） |
|
|
282
|
+
| `forge skills effectiveness` | 技能命中×任务成效关联（命中数/task数/avg分/弱占比，agent-neutral） |
|
|
283
|
+
| `forge skills eval-gen [--save] [--cases-only]` | 生成 eval 清单；`--save`/`--cases-only` 额外落结构化 case 集（回归闭环基准） |
|
|
284
|
+
| `forge skills eval-record --skill X --from <file/->` | 回填一次 eval run（agent dispatch 跑完每个 prompt 后整批提交，归一化+判定+算 health） |
|
|
285
|
+
| `forge skills eval-report --skill X` | latest run vs baseline 回归报告（regression 三态 + pass-rate delta + 可比性） |
|
|
286
|
+
| `forge skills eval-baseline --skill X` | 标记 baseline run（回归基准，显式人工决策） |
|
|
287
|
+
|
|
288
|
+
</details>
|
|
289
|
+
|
|
290
|
+
<details>
|
|
291
|
+
<summary><b>📊 可观测与维护</b></summary>
|
|
292
|
+
|
|
293
|
+
| 命令 | 说明 |
|
|
294
|
+
|------|------|
|
|
295
|
+
| `forge health [--json]` | 项目级质量趋势——聚合所有任务结论（分数走势/证据盲区率/复发低分维度，task→project 粒度联动） |
|
|
296
|
+
| `forge trace <task-ref>` | 查看任务的完整质量事件时间线（checklog + toollog + token） |
|
|
297
|
+
| `forge dashboard [--global] [--port <n>] [--no-open]` | 本地质量看板——起 HTTP 服务把分数走势/证据盲区率/复发低分维度/最近任务渲染成图形（localhost 只读，自动开浏览器，Ctrl+C 退出）。加 `--global` 聚合 `~/.forge/projects.json` 登记的全部项目（`forge init` 自登记），跨项目比对；项目被移走/删除后 `.forge/` 消失即自动淡出，不留幽灵路径 |
|
|
298
|
+
| `forge sync [--force]` | 同步 .forge/ 资产到当前二进制版本 |
|
|
299
|
+
| `forge clone check` | 检测文件代码克隆 |
|
|
300
|
+
| `forge plugin pack [--out <dir>] [--owner-name <n>]` | 生成多 host plugin pack（.claude-plugin/.cursor-plugin marketplace + plugins/\<name\>/ 树：claude manifest 含 hooks + 每 host 安装 README），让各 agent 一键 `plugin install forge` 跨工具接线（薄 manifest + 共享内容，单仓即 marketplace） |
|
|
301
|
+
| `forge plugin status` | 报告 forge plugin 是否在 user-level 已装（exit 0=已装，非零=未装；供 init-suggest hook / 脚本检测） |
|
|
302
|
+
| `forge plugin dedupe [dir] [--keep-empty]` | plugin 已装时清理 project-level 重复 hooks + 旧项目 .mcp.json forge server 残留，并清理 user-level `settings.local.json` 的重复 forge hooks；幂等 no-op；init-suggest SessionStart 自动调用（传 `--keep-empty` 保留项目 `settings.local.json` 为 `{}`）；user-level 始终保留文件壳（绝不删用户全局配置）；手动不传则项目级清完删空文件 |
|
|
303
|
+
|
|
304
|
+
</details>
|
|
305
|
+
|
|
306
|
+
## 📦 安装
|
|
307
|
+
|
|
308
|
+
```bash
|
|
309
|
+
# npm（推荐）
|
|
310
|
+
npm install -g @agent_forge/forge
|
|
311
|
+
|
|
312
|
+
# 或从 GitHub Releases 下载二进制
|
|
313
|
+
# https://github.com/MjxUpUp/Forge/releases
|
|
314
|
+
|
|
315
|
+
# 支持平台：macOS (x86_64/ARM64)、Linux (x86_64/ARM64)、Windows (x86_64)
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
<details>
|
|
319
|
+
<summary><b>📖 通过 Claude Code plugin marketplace（用户级，一次性接线）</b></summary>
|
|
320
|
+
|
|
321
|
+
若主要用 Claude Code，可走 plugin marketplace 一次性接线用户级 hooks（机器上所有项目共享，无需逐项目配 `.claude/settings.local.json`）：
|
|
322
|
+
|
|
323
|
+
```
|
|
324
|
+
/plugin marketplace add MjxUpUp/Forge
|
|
325
|
+
/plugin install forge@forge
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
仍需 `npm install -g @agent_forge/forge` 装二进制（hooks 都 spawn forge），并在每个项目 `forge init` 生成项目级资产（`.forge/`、`CLAUDE.md`/`AGENTS.md`、skills）。plugin 已装时 `forge init` 会自动去重 project-level 的 hooks，并清理 user-level `settings.local.json` 的重复 forge hooks（避免与 user-level plugin 双重注册——历史 global `forge init` 写 home / 旧全局安装残留的重复），存量项目由 init-suggest SessionStart hook 自动迁移。完整三步与各 host 差异见 `plugins/forge/README.md`。
|
|
329
|
+
|
|
330
|
+
</details>
|
|
331
|
+
|
|
332
|
+
## 🤝 贡献
|
|
333
|
+
|
|
334
|
+
欢迎提 Issue 和 PR。开发时注意：
|
|
335
|
+
|
|
336
|
+
1. **门禁先行** —— 任何源码变更走 `forge task` 三门禁（implement → verify → complete），不经任务的改动不被质量评分追踪。
|
|
337
|
+
2. **注释双语** —— Go godoc 采用形式 A（英文段 → 空 `//` → 中文段），中文不删、不单语；行内注释与字符串字面量不动。
|
|
338
|
+
3. **审查闭环** —— 提交前派独立只读子 agent 跑 code-review-gate 双轨（AI 作弊 + 工程规范），`forge review pass` 标记后才能过 task-complete 门禁。
|
|
339
|
+
4. **提交纪律** —— 只提交源码变更；排除 `docs/`、设计文档、`.claude/`、`.forge/` 工作目录。
|
|
340
|
+
|
|
341
|
+
详见 [质量协议](.claude/CLAUDE.md)。
|
|
342
|
+
|
|
343
|
+
## 📚 更多文档
|
|
344
|
+
|
|
345
|
+
| 文档 | 说明 |
|
|
346
|
+
|------|------|
|
|
347
|
+
| [中文使用指南](READMEs/README.zh-CN.md) | 面向国内用户的安装 / 日常 / 多宿主精简指南 |
|
|
348
|
+
| [Plugin 安装详解](plugins/forge/README.md) | 多 host plugin marketplace 三步接线与各 host 差异 |
|
|
349
|
+
| [项目主页](homepage/index.md) | 一分钟简介 + 核心能力速览 |
|
|
350
|
+
| [质量协议](.claude/CLAUDE.md) | Forge 质量协议全文（任务工作流 / 门禁 / 安全机制） |
|
|
351
|
+
|
|
352
|
+
## License
|
|
353
|
+
|
|
354
|
+
MIT
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
<div align="center">
|
|
359
|
+
|
|
360
|
+
<sub>⬆ <a href="#top">回到顶部</a></sub>
|
|
361
|
+
|
|
362
|
+
</div>
|
package/bin/forge.exe
ADDED
|
Binary file
|
package/package.json
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@agent_forge/forge-win32-x64",
|
|
3
|
+
"version": "1.15.1",
|
|
4
|
+
"description": "Forge native binary for win32-x64. Auto-installed via optionalDependencies of @agent_forge/forge; do not depend on directly.",
|
|
5
|
+
"os": [
|
|
6
|
+
"win32"
|
|
7
|
+
],
|
|
8
|
+
"cpu": [
|
|
9
|
+
"x64"
|
|
10
|
+
],
|
|
11
|
+
"files": [
|
|
12
|
+
"bin"
|
|
13
|
+
],
|
|
14
|
+
"license": "Apache-2.0",
|
|
15
|
+
"private": false
|
|
16
|
+
}
|