@agent_forge/forge-darwin-x64 1.84.0 → 1.84.2

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 (3) hide show
  1. package/bin/README.md +72 -387
  2. package/bin/forge +0 -0
  3. package/package.json +1 -1
package/bin/README.md CHANGED
@@ -17,34 +17,16 @@ Stop trusting AI-generated code. Start gating it.
17
17
  </div>
18
18
 
19
19
  <div align="center">
20
- <img src="docs/assets/dashboard-pulse.png" alt="Forge Pulse 全局质量面板" width="860"/>
21
- <p><sub>Forge Pulse —— 全局任务质量面板(跨项目事件流 / 任务评分与证据链 / Skills 聚合)</sub></p>
20
+ <img src="docs/assets/forge-demo.webp" alt="Forge 30 秒演示(自动播放,静音)" width="860"/>
21
+ <p><sub><b>30 秒演示</b>(自动播放,静音)—— 画面里的终端输出是真实 <code>forge docs lint</code> 跑出来的:两句没带证据的套话,被拦在提交之前。<br/>
22
+ 带音轨的 1080p 版本在 <a href="https://mjxupup.github.io/Forge/">网页播放器</a>,或直接下 <a href="docs/assets/forge-demo.mp4">mp4</a>。</sub></p>
22
23
  </div>
23
24
 
24
25
  ---
25
26
 
26
- <details>
27
- <summary><b>📖 目录</b></summary>
28
-
29
- - [核心功能](#-核心功能)
30
- - [快速开始](#-快速开始)
31
- - [它如何工作](#-它如何工作)
32
- - [定位:coding agent 循环的验证与状态层](#-定位coding-agent-循环的验证与状态层)
33
- - [工作流程](#-工作流程)
34
- - [Hook 系统](#-hook-系统)
35
- - [命令参考](#-命令参考)
36
- - [安装](#-安装)
37
- - [贡献](#-贡献)
38
- - [更多文档](#-更多文档)
39
- - [License](#license)
40
-
41
- </details>
42
-
43
- ---
44
-
45
27
  > **AI 写的代码,你放心直接提交吗?**
46
28
 
47
- Forge 在 AI 编码过程中自动插入结构化质量门禁——从任务创建到代码提交,确保每一步产出物都经过验证。配合 Claude Code 的 Hook 系统实现实时拦截,不需要你手动检查。
29
+ Forge 在 AI 编码过程中插入结构化质量门禁——从任务创建到代码提交,每一步产出物都要留下 deterministic 证据。配合 Claude Code 的 Hook 系统实时拦截,不需要你手动检查。
48
30
 
49
31
  **⚡ 60 秒拿到第一个证据**:
50
32
 
@@ -55,53 +37,17 @@ forge task verify-acceptance # 实跑验收标准 → 不可伪造的 determi
55
37
  forge trace feat/demo # 查看任务的完整证据链
56
38
  ```
57
39
 
58
- 跑 `forge eval wedge-drill` 可在任何机器上自检这条首证据路径(隔离环境,60 秒);`forge eval artifact-drill` 自检产物链分档执法全链(登记→hard/human 阻断→审批→提取验收实跑→漂移拦截→修复)。两者是发版 workflow 的行为级冒烟门禁与 nightly 的每日行为回归。
59
-
60
- ## ✨ 核心功能
61
-
62
- <table>
63
- <tr>
64
- <td width="50%" valign="top"><strong>🚦 任务级门禁</strong><br/>每个开发任务走 3 道门禁:实现 → 验证 → 完成,门禁之间有活动检查防止跳阶段。</td>
65
- <td width="50%" valign="top"><strong>🪝 实时 Hook 拦截</strong><br/>23 个内置 Hook,在 AI 写代码的同时自动检查质量、防止绕过(读改前置 / 文件监控 / 高危拦截)。</td>
66
- </tr>
67
- <tr>
68
- <td valign="top"><strong>🛡️ 安全纵深防御</strong><br/>三层防御架构:工具拦截 → 文件监控 → 自身保护。Agent 无法经 bash 绕道篡改。</td>
69
- <td valign="top"><strong>📊 质量评分</strong><br/>每个任务完成后自动评分,量化 AI 编码质量;deterministic 证据链可审计。</td>
70
- </tr>
71
- </table>
72
-
73
- ## 🚀 快速开始
74
-
75
- 需要 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 已安装。
40
+ 跑 `forge eval wedge-drill` 可在任何机器上自检这条首证据路径(隔离环境,60 秒);`forge eval artifact-drill` 自检产物链分档执法全链。两者是发版 workflow 的行为级冒烟门禁与 nightly 的每日行为回归。
76
41
 
77
- ```bash
78
- # 安装
79
- npm install -g @agent_forge/forge
42
+ ## 🎯 它补的是哪一层
80
43
 
81
- # 在项目目录初始化(默认零项目写入)
82
- cd your-project
83
- forge init
84
-
85
- # 在 Claude Code 中开始工作
86
- # AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程
87
- ```
88
-
89
- `forge init` **不在项目目录写任何文件**(不会被 git add 误提交),全部资产落在用户级:
90
-
91
- | 路径 | 说明 |
92
- |------|------|
93
- | `~/.forge/projects.json` | 全局项目注册表(forge 项目锚点) |
94
- | `~/.forge/projects/<key>/` | protocol.yml + runtime state(任务状态/hook 参考副本,key=git hash 或路径 hash) |
95
- | `~/.claude/settings.json` | Claude Code hooks(plugin 已装则由 plugin 接管,跳过此文件) |
96
- | `~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`、windsurf `global_rules.md` | 指针段(备份+幂等替换;激活判据锚定 `[forge-session]` managed 会话横幅,协议细节在 forge-quality skill 与 hook 即时提示,`forge uninstall --restore` 可回滚;版本变更后 autoSync 自动重刷新) |
97
- | `~/.claude/skills/forge-quality/` | 质量协议 Skill |
98
- | `~/.codex/hooks.json`、`~/.cursor/hooks.json` 等 | 其他 agent 的用户级 hook 接线(按检测到的工具) |
44
+ AI 编码是一个循环:写代码 → 运行 → 读反馈 → 修正 → 再写。这个循环由 coding agent(Claude Code、Codex、Cursor)驱动,**Forge 不替代循环本身**,只补上循环最容易缺的两层:**验证层**(每一轮产出物经门禁检验)与**状态层**(跨循环的任务状态与门禁历史——上下文一压缩就丢的那种)。
99
45
 
100
- > **团队要 git 共享同一份协议?** 用 `forge init --project`(团队模式)——`.forge/protocol.yml`、`CLAUDE.md`、`AGENTS.md` 等指令资产写入项目目录可提交共享;再跑一次普通 `forge init` 即转回零写入。
46
+ Forge 是 deterministic 的——范围是 "deterministic where code can verify":行为与意图的正确性留给 review 和人。判据与证据链归产品而非模型厂商,所以这一层不随模型代际贬值;模型变强时该删的是脚手架,不是传感器。
101
47
 
102
- > **主要用 Claude Code?** 走 [plugin marketplace](plugins/forge/README.md) 一次性接线用户级 hooks(机器上所有项目共享,连 `~/.claude/settings.json` 都不用动)。
48
+ <sub>完整论述(为什么是确定性门禁而不是让模型自检、退出码三态的设计依据)见 [docs/design/positioning.md](docs/design/positioning.md)。</sub>
103
49
 
104
- ## 🔧 它如何工作
50
+ ## 🔧 它是怎么跑的
105
51
 
106
52
  ```
107
53
  ┌──────────────────────────────────────────────────┐
@@ -113,7 +59,7 @@ forge init
113
59
  ┌──────────────────────────────────────────────────┐
114
60
  │ Forge Hooks · 实时拦截 │
115
61
  │ task-guard · read-before-edit · bash-guard │
116
- │ hazard-guard · file-sentinel · cheat-scan │
62
+ │ hazard-guard · file-sentinel · doc-lint │
117
63
  └────────────────────┬─────────────────────────────┘
118
64
  │
119
65
  ▼
@@ -126,66 +72,68 @@ forge init
126
72
  📊 质量评分 + deterministic 证据链
127
73
  ```
128
74
 
129
- 每轮 AI 编码循环都被门禁兜底:编译是否通过、断言有没有被弱化、改代码前是否真读过、文件有没有被绕道篡改——循环跑得越快,越需要自动化验证,而不是靠人盯着。
130
-
131
- ## 🎯 定位:coding agent 循环的验证与状态层
132
-
133
- **Forge is the verification and state layer for coding agent loops.** 用 harness engineering 的话说(Böckeler):computational sensor suite + durable state——代码能验证的交给确定性传感器,Forge 补的是持久状态;用 loop engineering 的话说(Osmani):loop 五构件里公开缺的正是 verification 与 memory 组件,Forge 就是这两块。
134
-
135
- AI 编码是一个循环:写代码 → 运行 → 读反馈 → 修正 → 再写。这个循环由 coding agent(Claude Code、Codex)驱动,**Forge 不替代循环本身**——它补上循环最容易缺的两层:
136
-
137
- - **验证层** — 每一轮产出物经门禁检验:编译通过、断言没被弱化、改代码前确实读过代码、文件未被绕道篡改、高危操作经人确认。循环跑得越快,越需要自动化验证兜底,而不是靠人盯着。
138
- - **状态层** — 跨循环的任务状态:3 道门禁(实现 → 验证 → 完成)、活跃任务追踪、门禁历史。"做到哪了 / 是否达标"有持久化、可审计的记录,而不是只活在 agent 的上下文里(上下文一压缩就丢)。
139
-
140
- 换言之,coding agent 负责**跑循环**,Forge 负责**让每一轮循环产出可信、状态可追**。Forge 是 deterministic 的——范围是 "deterministic where code can verify":行为/意图正确性是任何传感器的 remit 之外,那部分留给 review 与人。验证的判据与证据链归产品而非模型厂商,所以这一层不随模型代际贬值——模型变强时该删的是脚手架(feedforward),不是传感器(feedback)。
141
-
142
- <details>
143
- <summary><b>📖 为什么是确定性门禁,而不是让模型自检?</b></summary>
144
-
145
- 代码可执行(executable)是编码域相对研究/对话域的结构性优势——跑一遍 test / lint / compiler 拿到的退出码是**事实**,模型自评只是**概率判断**。Forge 的门禁尽量把判定交给确定性检查器,而非 LLM-as-judge:
146
-
147
- - **分层共识**("If code can verify it, don't ask an LLM to judge it"):LLM 审查作 advisory,deterministic build/test 作 hard gate。 Sonar 的 AC/DC(Agent Centric Development Cycle)是 Guide→Verify→Solve 三段闭环——同一确定性引擎前移进 agent 内环做 maker-checker 分离。
148
- - **Code-as-Harness 宣言**(arXiv:2605.18747):「termination should be governed by verification rather than by model confidence」——结束条件由验证决定,不由模型自信度决定。
149
- - **反直觉但关键**:模型越强、自主循环越长,越需要非模型的客观检查兜底——产出越快,无人复核的代码就越多;门禁是把吞吐量从 liability 变回 leverage 的那一个组件。
75
+ ## ✨ 核心能力
150
76
 
151
- Forge 退出码三态(`BLOCKED` 硬阻断 / `ADVISORY` 软信号 / 无前缀干净通过)即这一思路的落地:LLM 判定走 advisory,deterministic 事实走 hard。机械可判的模式(cheat-scan / scope-drift / read-before-edit / verify-acceptance)优先抽成 deterministic 扫描器,LLM-reviewer 退到只做语义判断。
152
-
153
- </details>
77
+ <table>
78
+ <tr>
79
+ <td width="50%" valign="top"><strong>🚦 任务级门禁</strong><br/>每个开发任务走 3 道门禁:实现 → 验证 → 完成,门禁之间有活动检查防止跳阶段。</td>
80
+ <td width="50%" valign="top"><strong>🪝 实时 Hook 拦截</strong><br/>27 个内置 Hook,在 AI 写代码的同时自动检查质量、防止绕过(读改前置 / 文件监控 / 高危拦截)。</td>
81
+ </tr>
82
+ <tr>
83
+ <td valign="top"><strong>🛡️ 安全纵深防御</strong><br/>三层防御架构:工具拦截 → 文件监控 → 自身保护。活跃任务内,Agent 无法经 bash 绕道篡改。</td>
84
+ <td valign="top"><strong>📊 质量评分</strong><br/>每个任务完成后自动评分,量化 AI 编码质量;deterministic 证据链可审计。</td>
85
+ </tr>
86
+ </table>
154
87
 
155
- ## 🔧 工作流程
88
+ ## 🚀 快速开始
156
89
 
157
- 每个开发任务自动走 3 道门禁:
90
+ 先装二进制(唯一权威步骤见下方 [📦 安装](#-安装)),然后在项目目录:
158
91
 
159
92
  ```bash
160
- forge task start --ref feat/add-login --branch --accept "go test -v ./... :: PASS" # 创建任务+分支+登记验收标准(--accept 可重复;Expected 是输出子串匹配;go test 带 Expected 或 contains/not-contains 断言忘加 -v 时 start 自动补——无 -v 无 PASS 行永不匹配)
161
- forge task start --ref feat/login --worktree [--base main] [--wt-dir <父目录>] # 在 repo 树外为此任务创建独立 worktree+分支+绑定(多任务并发隔离形态,multi-task-concurrency L4;<repo 父目录>/<repo 名>-wt/<分支> 默认)
162
- forge task start --ref feat/add-login --scope "internal/auth/*.go" # 声明计划改动白名单(规划前置→可度量契约,advisory 检测 scope-drift)
163
- forge task start --ref feat/add-login --tier mini # 方案档位:none 直接改 / mini 小方案 / full 完整方案;与硬触发器(迁移/schema/接口契约/鉴权/依赖/跨模块)推导档位取较高者,下调须 --tier-reason 写明理由(advisory)
164
- # 规则表可在 protocol.yml 的 design_tiers 段覆盖:rules(按 name 追加或替换内置规则,tier 取 mini/full,paths 支持 seg:<目录名> / 含 / 的路径 glob 或目录前缀 / 文件名 glob)、standard_changes(追加不触发档位的例行改动)、replace_defaults(弃用内置规则与内置例行改动)
165
- forge task start --ref feat/frontend --assignee kimi --role frontend --depends-on feat/api # 创建即分派给 kimi(offered),声明上游依赖 feat/api(DAG 环检测;task-verify/task-complete 在 feat/api 交付前阻断)
166
- forge task start --ref feat/hotfix --assignee kimi --ttl 24h # per-task TTL 覆盖全局 7d 僵尸窗口:短时效分派 24h 无活动即标僵尸(offered/claimed/input-required 通用;0=用全局默认)
167
- # AI 自动完成工作...
168
- forge task gate task-implement # ✅ 代码实现(advisory:编译/断言提醒,agent 自检)
169
- forge task verify-acceptance # ✅ 实跑验收标准,记 deterministic 证据(spec-as-gate)
170
- forge task gate task-verify # ✅ 测试验证
171
- forge task scope show # 查看声明白名单 + 实时 scope-drift(advisory,不阻塞)
172
- forge task gate task-complete # ✅ 完成确认(第三道门禁;门禁全过 ≠ 任务完结)
173
- forge task complete # 🏁 任务完结:MarkComplete + 自动评分 + Act 结论 + 清 active ref(2026-08-18 死锁修复后完成标记归属本命令——门禁只过不 complete 会留僵尸任务)
174
- forge task score # 查看质量评分
93
+ cd your-project
94
+ forge init # 默认零项目写入,全部资产落在用户级
95
+ # 回到 Claude Code 继续工作:AI 会自动读取 Forge 生成的 Skill 并驱动门禁流程
175
96
  ```
176
97
 
177
- <details>
178
- <summary><b>📖 门禁细节:退出码契约 / PlanScope / Cheat-scan</b></summary>
98
+ 主路径是 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)——hooks 经它的 Hook 机制接线;Codex、Cursor、Windsurf、dsh 等 12 种宿主同样支持(接线差异见 [plugins/forge/README.md](plugins/forge/README.md) 与 [中文 README](READMEs/README.zh-CN.md))。
179
99
 
180
- 门禁之间有时间和活动检查,防止 AI 跳过阶段直接提交。`task-implement` 的编译/断言检查为 advisory 提醒(由 agent 自检,不阻塞)——forge 技术栈无关,适配 loop engineering。`forge task verify-acceptance` 实跑 `task start --accept` 登记的验收标准(`Run :: Expected`),把 dev-workflow Plan 的验收条件从 plan 文本变成不可伪造的 deterministic 证据——对冲 agent 自述"满足验收"却没真跑的盲区。`forge task complete` 对非 generic 任务硬前置至少一条登记验收标准(零验收 = 考卷缺位拒绝完成;考卷来源分级盖章:spec-extract > start > conventions 兜底 > manual 补登,交付验收单如实披露各层级计数)。
100
+ `forge init` **不在项目目录写任何文件**(不会被 git add 误提交),全部资产落在用户级:
181
101
 
182
- **门禁退出码契约**:`forge task gate` 非 0 退出(输出 `BLOCKED:` 前缀)= 硬阻断,必须修复后重跑;零退出但见 `ADVISORY:` 前缀 = 软信号(gate 仍过、已记 checklog,应修不阻断)。按退出码而非文案行动——硬错误的散文易被误读成提醒而跳过。
102
+ | 路径 | 说明 |
103
+ |------|------|
104
+ | `~/.forge/projects.json` | 全局项目注册表(forge 项目锚点) |
105
+ | `~/.forge/projects/<key>/` | protocol.yml + runtime state(任务状态/hook 参考副本,key=git hash 或路径 hash) |
106
+ | `~/.claude/settings.json` | Claude Code hooks(plugin 已装则由 plugin 接管,跳过此文件) |
107
+ | `~/.claude/CLAUDE.md`、`~/.codex/AGENTS.md`、windsurf `global_rules.md` | 指针段(备份+幂等替换;激活判据锚定 `[forge-session]` managed 会话横幅,协议细节在 forge-quality skill 与 hook 即时提示,`forge uninstall --restore` 可回滚;版本变更后 autoSync 自动重刷新) |
108
+ | `~/.claude/skills/forge-quality/` | 质量协议 Skill |
109
+ | `~/.codex/hooks.json`、`~/.cursor/hooks.json` 等 | 其他 agent 的用户级 hook 接线(按检测到的工具) |
183
110
 
184
- **PlanScope 白名单(规划前置)**:`task start --scope <glob>`(可重复,或中途 `forge task scope add <glob>` 追加)声明"打算改哪些文件"。`task-verify` 比对实改源码与声明的差集,记一条 `scope-drift` 证据(deterministic,`forge trace` 可见)并 stderr 提醒。全程 **advisory 不阻塞**——变更影响分析召回率仅 ~44%,scope 是 prediction 非 contract,偏差是常态信号而非异常;它把"规划前置"变成可度量、可回顾的契约,正堵在 review 反复出问题的根因上。
111
+ > **团队要 git 共享同一份协议?** 用 `forge init --project`(团队模式)——`.forge/protocol.yml`、`CLAUDE.md`、`AGENTS.md` 等指令资产写入项目目录可提交共享;再跑一次普通 `forge init` 即转回零写入。
185
112
 
186
- **Cheat-scan(机械作弊模式扫描)**:`task-verify` 扫任务新增行(`+` 行),机械检测 7 类 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`(某文件新增行全注释零逻辑)、`comment-as-debt`(新增债务注释标记不解决)、`phantom-import`(相对 import 解析不到磁盘文件)、`path-assumption`(OS 路径分隔符被当内容匹配器,如 `HasPrefix(line, string(filepath.Separator))`——跨平台崩溃指纹)——记一条 `cheat-scan` 证据(deterministic,`forge trace` 可见)并 stderr 列出命中。全程 **advisory 不阻塞**:这些模式此前全靠 code-review-gate 的 LLM 子 agent 判断,LLM 每轮对同一 diff 重新采样抓不同子集,是"每轮 review 冒新问题"的体感来源;抽到 deterministic 后,机械模式一次判准,LLM-reviewer 退到只做语义判断(设计/架构/mock 是否幻觉)。`comment-only-fix` 是启发式(severity=low,纯文档任务可能误报)。
113
+ > **主要用 Claude Code?** 走 [plugin marketplace](plugins/forge/README.md) 一次性接线用户级 hooks(机器上所有项目共享,连 `~/.claude/settings.json` 都不用动)。
187
114
 
188
- </details>
115
+ ## 📋 命令速查
116
+
117
+ 日常最常用的几条。**完整命令表**(每个 flag、逃生舱、门禁语义)在 [docs/reference/cli.md](docs/reference/cli.md)。
118
+
119
+ | 命令 | 用途 |
120
+ |------|------|
121
+ | `forge init` | 初始化项目(默认零项目写入) |
122
+ | `forge next` | 从 git/任务状态推导**恰好一条**下一步命令——agent 不自选下一步 |
123
+ | `forge task start --ref <type/desc> --branch --accept "run :: expected"` | 建任务 + 建分支 + 登记验收标准 |
124
+ | `forge task gate <gate-id>` | 推进门禁:task-implement → task-verify → task-complete |
125
+ | `forge task verify-acceptance` | 实跑验收标准,落 deterministic 证据 |
126
+ | `forge task complete` | 完结任务:自动评分 + Act 结论 + 清 active ref |
127
+ | `forge task report` | 交付验收单(考卷逐条结果 + 证据强度 + 未验证面) |
128
+ | `forge task resume --match "<关键词>"` | 跨会话/跨工具拉回任务上下文 |
129
+ | `forge review pass` / `forge review status` | 代码审查标记与状态 |
130
+ | `forge gate push` | git 推送边界门禁(cheat-scan 复检 + 未消解 BLOCKED 任务) |
131
+ | `forge hazard confirm --last` | 确认最近一条被拦高危命令(须真人终端) |
132
+ | `forge freeze <路径>...` | 冻结写入范围,冻结路径之外的写全部硬阻断 |
133
+ | `forge trace <ref>` / `forge health` / `forge dashboard` | 证据链时间线 / 质量趋势 / 全局看板(Pulse) |
134
+ | `forge doctor` / `forge status` | 环境一致性审计 / 项目状态 |
135
+
136
+ 其余命令族(`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`)见同一份[完整命令表](docs/reference/cli.md)。
189
137
 
190
138
  ## 🪝 Hook 系统
191
139
 
@@ -197,276 +145,15 @@ Layer 1: PreToolUse 快速拦截
197
145
  └─ bash-guard: Bash → 检测写文件模式
198
146
 
199
147
  Layer 2: PostToolUse 文件监控
200
- └─ file-sentinel: Bash → 对比执行前后 git 状态,未授权变更自动 revert
148
+ └─ file-sentinel: Bash → 对比执行前后 git 状态,未授权变更隔离到 DataDir/quarantine/(可恢复)
201
149
 
202
150
  Layer 3: 会话结束验证
203
151
  └─ task-verify: 检查任务完成度 + 主分支保护 + 自身版本
204
152
  ```
205
153
 
206
- Agent 无法通过 `node -e "fs.writeFileSync()"`、`cat > file`、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层,file-sentinel 监控文件层,task-guard 保护配置层。
207
-
208
- <details>
209
- <summary><b>📖 内置 Hook 完整清单(23 个)</b></summary>
210
-
211
- | Hook | 触发时机 | 功能 |
212
- |------|----------|------|
213
- | **task-guard** | Write/Edit 前 | 无活跃任务时 WARN(仅 `.forge/*`/`.claude/settings*` 自保护 FAIL——此类项目级文件只在团队模式/老项目存在),保护 Forge 配置不被篡改 |
214
- | **freeze-guard** | Write/Edit 前 | `forge freeze <路径>...` 激活后硬阻断冻结路径之外的 Write/Edit——「只改这里别动其他」的 session 级硬护栏(on-demand-guards /freeze 的 forge 侧落地);多路径、相对路径归一化、Windows 大小写不敏感;排在 task-guard 之前优先判定;`forge freeze --off` 解除 |
215
- | **read-before-edit** | Write/Edit 前(活跃任务内) | 编辑本会话未 Read 过的现存源文件 → 硬阻断(`BLOCKED`)。Edit 需精确匹配旧文本,未读即凭记忆盲改——old_string 撞中即错改入库,先 Read 再 Edit。豁免新建文件/测试文件/非源码;批量重构逃生 `forge task override --work-activity disable`(记 checklog 审计;work-activity 是节奏门禁,不降 evidence 强度)。reads-log 落盘随会话存活,压缩后仍累计 |
216
- | **assertion-check** | Write/Edit 前 | 检测断言弱化(t.Fatal → t.Log、assert! 被删除等),advisory 提醒不阻塞(agent 自检) |
217
- | **bash-guard** | Bash 前 | 检测命令中的写文件模式(writeFile、cat >、sed -i 等),无任务时 WARN(源码随后被 file-sentinel 隔离) |
218
- | **gate-cmd-form** | Bash 前 | 门禁命令嵌组合形态(分号续行/截断管道/grep 掩蔽/\|\| 链/多门禁连刷)时 **BLOCKED 拦截**——分号让前一门禁 BLOCKED 后链条照走、截断管道吞掉 BLOCKED 文本面,退出码契约被系统性削弱(设计 C;delivery-hardening 墙-1a:1.67 机械版本门 ratchet 生效,会话阻断上限 5 有界;逃生 FORGE_GATE_CMD_FORM=0 落 checklog 审计;重发为单条门禁命令或仅用 && 串联) |
219
- | **hazard-guard** | Bash 前 | 高危命令(`rm -rf`、`git push --force`、`DROP TABLE/SCHEMA`、`TRUNCATE`、`GRANT ALL`、`kubectl delete`、`docker system prune`、无 WHERE 的 `DELETE/UPDATE`、解释器内联删除如 `python -c "os.remove(...)"` 等)human-in-the-loop 拦截:block + 指引 agent 向用户说明风险 → 用户在自己的终端运行 `forge hazard confirm --last` 登记 5min 限时标记(confirm 只接受真人终端)→ 重试放行(confirm 链是唯一放行路径,`FORGE_ALLOW_HAZARD` 已移除) |
220
- | **auto-compile** | Write/Edit 后 | advisory 提醒用对应技术栈编译命令自检(go build / cargo check / mvn / tsc 等),不强制编译 |
221
- | **workflow-test-guard** | Write/Edit 后 | 改 `.github/workflows/*.yml` 后自动跑 `internal/ci` 守护测试,把"沙盒异常"即时反馈给 agent(不依赖 CI 兜底),是 release.yml test→goreleaser→npm needs 链的实时守护层 |
222
- | **file-sentinel** | Bash 后 | 监控文件变更,未授权修改隔离到 DataDir/quarantine/(`forge data-dir` 查看路径,可恢复,不删除) |
223
- | **tool-track** | Read/Skill/Agent/Grep/Glob/Bash 后 | 静默记录工具调用到 toollog(Read/Skill/Agent 记名称、Bash 记截断命令、Grep/Glob 记截断 input——探索调用也计入 work-activity),供 read-before-edit 门禁与 efficiency 维度评分判断(agent 是否先读代码再改、质量 skill 是否被驱动) |
224
- | **failure-track** | 命令失败后(PostToolUseFailure) | 记录 CheckToolFailure 观察;失败文本命中编译/测试类指纹(`undefined:`/`error TS`/`error[E`/`--- FAIL` 等)时注入 compile-fix-loop skill 事实性指针(advisory 不阻断——失败已发生) |
225
- | **subagent-track** | 子 agent 结束(SubagentStop) | 记录 agent_id/agent_type/交付长度+首行摘要到 checklog(归因数据——此前子 agent 活动 forge 侧零记录);纯观察,无输出无阻断 |
226
- | **test-nudge** | Write/Edit 后(活跃任务内) | 事中测试提醒:连写 ≥3 个源码文件且无配对测试写入时注入一次 test-discipline skill 事实性提示(advisory,每连写只提示一次);测试写入重置计数;无任务静默;执法仍在 task-verify 门禁 |
227
- | **task-verify** | 会话结束 | 任务门禁/主分支保护到 stderr+checklog(advisory);活跃任务 + 未提交代码变更时有界阻断 Stop(每会话最多 3 次,超限回落 advisory;逃生 `FORGE_TASK_VERIFY_STOP=0`) |
228
- | **review-stop** | 会话结束 | code-review-gate 自动挡:未审源码变更 block 会话结束。task 模式不重复拦(task-complete 门禁 ReviewPassed 硬前置已强制),非 task 模式按 diff stamp 决策;并发会话检测——其他 session 有活跃任务时放行(调研 session 不被拦) |
229
- | **skill-scan** | 会话开始 | advisory:扫描 ~/.claude/skills 安全性(`forge skills audit`,21 条安全规则),补 install 门控缺口(手动 clone/junction/git pull 进入的 skill),全局 hook 不依赖 forge project |
230
- | **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 |
231
- | **init-suggest** | 会话开始 | advisory,接管决策引擎(P2 起默认 **ask**):declined(标记+注册表双检)→静默;已接管→顺带 dedupe;外来 harness 信号(P4)→让位并记 declined;takeover 偏好 auto(`FORGE_TAKEOVER`/`forge config`/legacy `FORGE_AUTO_INIT=1`)→静默 init;off→静默;ask→每项目首次询问一次(拒绝→`forge off`;全程询问 →`forge config set` takeover 为 auto)。v1.22 起 init 零项目写入 |
232
- | **task-resume** | 会话开始 | advisory:只输出 `[forge-session]` 管理横幅一行(用户级 CLAUDE.md 据此判断是否启用 forge 协议)。不注入接续视图、不锚定 session、不推送待认领任务——接续按需拉取:用户说「继续某某任务」走 `forge task resume --match`,说「还有哪些任务没完成」走 `forge task list --open`;项目级 hook |
233
- | **compact-resume** | 压缩后(claude-code / codex) | PostCompact 时设 `ResumeStale=true` 标志(PostCompact 不在 additionalContext 注入点,只设标志等下个 prompt 重注入),context-rot 抗机制根治层·设标志半边 |
234
- | **resume-reinject** | 用户提交时(claude-code / codex) | 检测 `ResumeStale=true`(刚压缩过)→ 输出当前任务的完整接续上下文并清标志;未压缩时静默。压缩只丢当前 session 的工作记忆,补回它不打扰用户,context-rot 抗机制根治层·重注入半边 |
235
- | **doc-lint** | PostToolUse(Write\|Edit) | advisory:被写的 .md 命中 D1-D11 L1 规则时注入命中清单(规则/行号/修复方向,按命中签名会话内去重),写时反馈提前于 complete 的 doc gate(output-readability-gates-v2.md P1-C),Go 原生实现 |
236
- | **skill-trigger** | 多事件(Pre/PostToolUse、SessionStart、Stop、UserPromptSubmit,按宿主能力接线) | 通用声明式 skill 触发判定:按各 skill `metadata.triggers` 的 event/when 条件(coding_intent / source_changed_uncommitted / test_command_failed / task_active_no_review / skill_file_touched)匹配上下文,advisory 注入 skill 加载指引;Go 原生实现(failure-track/subagent-track/test-nudge 亦然,其余 18 个为内嵌 bash 脚本) |
237
-
238
- </details>
239
-
240
- ## 📋 命令参考
241
-
242
- <details>
243
- <summary><b>🔧 项目管理</b></summary>
244
-
245
- | 命令 | 说明 |
246
- |------|------|
247
- | `forge init` | 初始化项目(默认**零项目写入**:登记全局注册表 `~/.forge/projects.json`,hooks/指令/skill 全在用户级,protocol.yml + runtime state 在 `~/.forge/projects/<key>/`;`--project` 团队模式把指令资产写项目目录供 git 共享;旧的 `--mode` 标志已废弃为 no-op) |
248
- | `forge status [--json] [--system]` | 查看项目状态(任务管道 + 质量信号);`--system` 跑系统级健康检查(~/.forge、PATH、孤儿 hook、skills manifest) |
249
- | `forge verify` | 项目完整性检查 + 回归测试 |
250
- | `forge update [--apply] [--plugin]` | 检查并更新到最新版本(按安装通道分流:npm 安装自动检测包管理器 npm/pnpm/yarn,查 npm registry 并打印对应更新命令——npm 包不可变,原地替换会被下次 install 还原,故不代下载,可用 `FORGE_NPM_REGISTRY` 覆盖 registry;GitHub Release/手动安装从 GitHub 下载自替换);npm 通道加 `--apply` 直接代跑包管理器安装命令并自验新版本(发布流程硬化 2026-09:打印的命令 ≠ 装上的版本——发布者本机曾停在旧版直到人工质疑;Windows 运行中二进制被锁,提示手动命令);加 `--plugin` 在更新后打印 plugin marketplace 重装指引(marketplace 镜像同步 hook 时建议重装) |
251
- | `forge off [--all] [--commit]` 或 `forge on` | 按项目退出/恢复接管(Project Policy Layer):`off` 把当前项目(git 根)置为 declined——项目级 hook 全部静默、`forge init`/`FORGE_AUTO_INIT`/自动接管拒绝(退出不被任何默认路径重置);`--all` 一键全退;`--commit` 额外在仓库根写 `.forge-decline` 团队声明(committed 后对所有协作者让位,deny-wins);`on` 是 declined→managed 的唯一恢复通道(清标记与声明文件,从未 init 的项目提示先 `forge init`)。状态存注册表条目(含决策来源/时间审计),`forge status` 退出码即「是否 managed」 |
252
- | `forge config get/set takeover` | 用户级接管偏好(`~/.forge/config.json`):**ask(出厂默认)**每项目首次接触询问一次;**auto** 静默接管全部 git 项目(P2 之前的行为;declined 与外来 harness 让位仍生效);**off** 不接管不询问。env 覆盖:`FORGE_TAKEOVER=ask\|auto\|off`(legacy `FORGE_AUTO_INIT=1` ≡ auto);`--raw` 只输出值供脚本消费 |
253
- | `forge policy state` / `forge policy yield` | 接管策略快查/外来 harness 让位:`state` 打印当前目录三态(managed\|declined\|unknown,退出码恒 0,init-suggest bash 以此分流);`yield` 检测外来 harness 高置信信号(`.specify/`、`.claude/commands`、`.claude/settings.json` 含 hooks/permissions、`.cursor/rules`——单一真相源 internal/harnessdetect),命中即让位(declined, by=foreign-harness)并打印说明,`forge on` 显式覆盖 |
254
- | `forge conventions init [--force]` | 项目规范档案(conventions-profile):机械扫描本仓库**已声明**的规范——AGENTS.md/CLAUDE.md/.github/copilot-instructions.md 等规范文件、lint/format 配置、stack 工具链命令——写入用户级档案 `~/.forge/projects/<key>/conventions/`;此后 hook 按宿主能力注入:会话开始注入 ≤15 行摘要(支持 PostCompact 的宿主压缩后重注入),写源码文件时注入规范文件指针+同目录范例(advisory 不阻断;同一份档案跨宿主共享);摘要的「提取要点」节由 agent 代码考古增补,重跑 init 保留提炼内容(`--force` 才重建骨架);规范源文件变化后指纹翻转,注入与 show 均提示重扫;task-verify 会提醒「档案声明的 lint 命令本任务未跑」(advisory,提醒与 checklog 审计行经 `FORGE_CONVENTIONS_LINT=disable` 一并静默) |
255
- | `forge conventions show` | 查看规范档案:stack/lint/test/build 命令、规范声明文件与 lint 配置清单、fingerprint 与过期状态(STALE=源已漂移,重跑 `forge conventions init` 刷新)、摘要全文 |
256
- | `forge conventions learn <rule>` | 纠正增量写回(conventions-profile):用户/审查指出规范违规时当场把该规则写进摘要提取要点节(一字不差去重、替换待提取占位、超 15 行预算警告——注入截断至 15 行,全文仍在 summary.md)——纠正离开会话上下文进持久档案,下个会话注入即生效 |
257
- | `forge uninstall [--restore]` | 一键反装:剥除全部用户级 hooks(claude/codex/cursor/windsurf/opencode/kimi/reasonix/cline/codebuddy/zcode;dsh 无用户级 hook 文件可剥——其 translator 是刻意 no-op,卸载即移除 plugin)+ 用户级指令段(CLAUDE.md/AGENTS.md/global_rules.md)+ forge-quality skill + 清 npm global `@agent_forge/forge` + 删 init-suggest 标记(默认 `~/.forge/.init-suggested/`,设 `FORGE_DATA_HOME` 时落该根下);`--restore` 把用户级文件回滚到 forge 修改前字节(备份在 `~/.forge/backups/`);plugin 卸载须在 agent CLI 内交互运行(不可脚本化) |
258
- | `forge migrate [--dry-run] [--force]` | 把旧 `.forge/` runtime state(tasks/gates/checklog/toollog/act/sessions/quarantine/active-task-ref 等)迁到用户级 DataDir(`~/.forge/projects/<key>/`)——升级到 runtime state 外迁版本后的迁移路径;未改过的 `.forge/protocol.yml` 由 autoSync 自动迁 DataDir,用户改过的保留为团队共享覆盖层;迁移的 task 文件落地即剥离外来门禁信号(review/验收/评分/完成/逃生舱/generic 须本机重挣,验收命令带外来标记);幂等,`--dry-run` 预览,`--force` 覆盖 DataDir 已有同名 |
259
- | `forge registry prune` | 精简全局注册表 `~/.forge/projects.json`——移除项目目录已不存在的死路径与重复条目(项目移走/删除/测试残留),原子写回。registry.List 读时惰性精简但只在 `forge dashboard` 启动时触发(启 web 阻塞),本命令给不启 web 的主动清理入口 |
260
- | `forge registry remove <path>` | 按路径移除单条注册表条目(精确匹配、不做前缀;路径形态与大小写归一容忍——8.3 短名/符号链接解析形态/大小写变体命中同一条)。与 prune 分工:prune 只能清**死**路径,活着的伪根(如误注册的用户 home/临时根——此类条目 registry.Add 已有保留根守卫拒绝再入册)只能具名移除 |
261
- | `forge registry gc [--prune]` | 回收孤儿项目数据目录(`~/.forge/projects/<key>/` 下不在注册表内的目录,测试泄漏/项目注销残留的无界增长收口):默认 dry-run 只报告;`--prune` 执行——空目录树删除,最新文件超过 14 天的非空目录移入 `~/.forge/backups/gc-<时间戳>/`(移动而非删除,可恢复),14 天内有活动的未登记项目数据与已登记项目永不触碰 |
262
- | `forge registry audit [--json]` | 只读一致性审计:key-drift(注册表 key ≠ 当前派生 key 且旧数据目录有载荷,提示 `forge project adopt` 迁移)/ orphan-datadir(数据目录有载荷但注册表无条目,备份壳除外)/ id-collision(两个路径派生同一 key——复制粘贴共享 `.forge-project-id` 的检出器)/ invalid-id(ID 文件格式非法,Key() fail-open 回落的唯一暴露面) |
263
- | `forge registry rekey --from <key> --to <key> [--dry-run]` | 把 from key 的项目数据目录并入 to key(修复身份分裂的存量数据;合并语义与 project import 共享 datamerge) |
264
- | `forge project adopt [--dry-run] [--regenerate]` | 采纳 repo-born 项目 ID:在主 worktree 根生成 `.forge-project-id`(`fpid_<32hex>`,建议 commit 进 git),并把本机数据从路径 key 迁到 ID key(先迁数据再翻身份,复用 rekey 合并语义)+ 注册表同步。另一台机器 `git pull` 拿到 ID 后跑一次 adopt 即对齐——两台机器对同一 clone 推导同一 key,跨机器同步免重映射;`--regenerate` 给共享/污染 ID 换新(其他机器需重跑 adopt 处理 key 不匹配) |
265
- | `forge project export [--out <file>] [--include quarantine,hazards]` | 把项目记录打包为跨机器 bundle(tar.gz + 逐文件 sha256 的 manifest):allowlist 默认拒绝——只带 tasks/checklog/toollog/sessions/act/stamps(除 hook-deploy)/protocol.yml,quarantine 源码全文与 hazards 命令行等敏感 store 须 `--include` 显式选入,会话锚/sentinel/freeze 等机器本地文件一律排除;manifest 记录来源身份(key/key_mode/project_id)供导入侧 lineage 判定 |
266
- | `forge project import <bundle> [--dry-run] [--untrusted] [--trust-foreign] [--force] [--adopt-id]` | 校验(sha256+版本守卫+路径安全)并合并 bundle 到本机:同 key = 同身份 lineage 默认保留结果字段(评分/完成/门禁历史经单调合并收敛),session 链接恒幽灵化;key 不匹配默认剥离外来门禁信号(`--trust-foreign` 显式放行);bundle 来自 ID 身份而本机是路径身份时默认拒绝给指引,`--adopt-id` 直接采纳其 ID(本机数据先迁移);账本 `imports.jsonl` 保证同 bundle 重复导入跳过,jsonl 精确行去重保证重叠导出不重复——双向同步收敛 |
267
- | `forge node show [--json]` | 显示本机节点身份(node-identity:多机器同步的机器归因地基):`node_id` = ed25519 公钥指纹(`fnode_<32hex>`,身份即公钥——验签即身份证明),密钥对存于用户级 `~/.forge/node.json`(私钥 0600,永不外泄也不进 bundle),`rotation_chain` 轮换证书链格式预留(v1 恒空);输出只含 node_id + 公钥,绝不打印私钥 |
268
- | `forge project sync <init\|push\|pull\|status>` | 多机器持续同步(git 传输通道):`init <remote>` 绑定任意 git remote(固定 `forge-sync` 分支,免疫各机默认分支漂移);`push` 导出 bundle 到 `nodes/<node_id>/<key>/bundle.tar.gz` 并推送(每节点只写自己前缀,git 写权限即权限层;同时写 `.sig` 签名 sidecar);`pull` 拉取后经标准 `project import` 导入全部他机 bundle(账本幂等,重复 pull 免费;lineage 裁决信任;逐节点容错 + 节点目录形态校验);`status` 显示绑定与最近操作时间。机器本地绑定存 `DataDir/sync-remote.json`(allowlist 默认拒绝,不随 bundle 旅行),缓存仓库在 `~/.forge/sync-cache/` |
269
- | `forge trust <list\|add\|remove\|require-signed>` | 节点信任 store(TOFU,node-identity §3):`add <node_id> <pubkey> [--label <备注>] [--profile personal\|team]` 带外核对指纹后登记对端(node_id 与公钥一致性强制校验);`require-signed on` 切团队档——bundle 必须带有效签名且签名者已登记,否则导入硬拒;签名无效(篡改/公钥不符)任何档位都硬拒。store 存 `~/.forge/trust.json`(0600,永不随 bundle 旅行) |
270
- | `forge workspace create <name>` | 创建空多仓 workspace(用户级清单 `~/.forge/workspaces.json`,与 projects.json 平级;一组共同交付的 forge 项目 key 的逻辑分组,机器本地配置、不进 project sync bundle) |
271
- | `forge workspace add <name> [--path <dir>]` | 把 repo 加入 workspace(默认当前项目,`--path` 指定他仓);成员按项目 key 引用(path 仅是展示缓存,漂移由 doctor 检出),同一 repo 允许属于多个 workspace |
272
- | `forge workspace remove <name> [--path <dir>]` 或 `forge workspace remove <name> --key <key>` | 从 workspace 移除成员(默认当前项目);`--key` 逃生口:repo 已删/搬移无法按路径推导 key 时按存储 key 移除 |
273
- | `forge workspace list [--json]` | 列出全部 workspace 及成员(key + 缓存路径) |
274
- | `forge workspace status <name>` | 读侧聚合:按 key 扫描各成员仓活跃任务(ref/gate 进度/branch);单个成员坏了告警跳过,绝不让整视图空白 |
275
- | `forge workspace doctor [--json]` | 检出清单 drift(全部 advisory 不阻断):成员 key 未注册 / 缓存路径缺失或与 registry 现路径分叉 / 一 key 属多个 workspace / 空 workspace / 跨仓任务依赖环(dep-cycle,点名完整 key:ref 环序列供人工摘边) |
276
- | `forge worktree janitor` | worktree 生命周期清理(multi-task-concurrency L4):只清理【任务已完成或超期 14d 且工作树干净】的 workspace(脏的只报告——免删除条款,绝不自动删有未提交工作的 worktree);路径已消失的死锚绑定无条件清除。多任务并发的磁盘上界管理 |
277
- | `forge harness init [--from-existing] [--remote <url>] [--yes]` | 建立研发控制面仓库(multi-task-concurrency T6):把用户级 `~/.forge` 变成私有 git 仓库——tasks/checklog/archive 入库获 git 史,stamps/hazards(信任锚)/workspaces/attribution(机器本地)/会话簿记 gitignore 永不外发。HITL:交互确认仅在终端(TTY)进行——agent 经 Bash 调用无 TTY 被拒(agent 不得代批);`--yes` 仅脚本化 CI 逃生口;`--from-existing` 给存量 DataDir 做一次基线提交(不重写数据) |
278
- | `forge harness status` | harness repo 状态:未建立 / 本地 / 已连远端 + 近期提交 + 未提交计数 |
279
- | `forge harness push [--yes]` | 推送 harness repo 到私有远端(首推是独立外发 HITL——数据出境清单:tracked 类别 / 永不外发类别 / 远端必须私有;凭据走你自己的 git credential helper,forge 不持有凭据);后续 push 常规。`--yes` 仅脚本化 CI |
280
- | `forge harness pull` | 从远端拉取(冲突上浮人工解决,机器绝不自动裁决) |
281
- | `forge task finish [--merge-to <branch>] [--keep]` | worktree 任务收尾:验证门禁完成后在主检出合并分支(合并前校验主检出 HEAD 在目标分支上,错配拒绝)→ 清理 worktree → 解绑;`--keep` 合并后保留 worktree。脏工作树拒绝(免删除条款) |
282
-
283
- </details>
284
-
285
- <details>
286
- <summary><b>🚦 任务管理</b></summary>
287
-
288
- | 命令 | 说明 |
289
- |------|------|
290
- | `forge task start --ref <type/desc> --branch` | 创建任务(自动创建分支);`--depends-on <ref>` 声明上游依赖(task-verify/task-complete 在上游交付前阻断),支持 `<key>:<ref>` 跨仓依赖——key 须为本 repo 所属 workspace 的成员(`forge workspace add`),缺失目标按保守 pending 处理 |
291
- | `forge next [--json]` | 单命令引导:从 git/任务状态推导**恰好一条**下一步命令+理由(无任务有脏树→task start/wild 申报;门禁链→下一步命令:implement→验收实跑→verify→review pass→complete 门→complete)。agent 不自选下一步——pull 侧引导与 push 侧 hook 执法互补 |
292
- | `forge task intent "<注记>"` | 追加意图注记(三段工件之 intent 段):append-only——没有覆写/删除入口,意图历史即决策史,防轮次重写导致的语义漂移(rot) |
293
- | `forge task checklist add/tick/drop` | 操作对账单(checklist 段):勾选即进度、断点存活,task-complete 硬门禁要求全勾(report 写完不算 done,checkbox 才算) |
294
- | `forge task start --invariant "run :: expected"` | 析出不变量(instrument 段):声明期校验必须是可执行命令(叙述性约束被拒并指引降级到 checklist/intent),映射进验收标准——机器对账/freshness/complete 前置全覆盖 |
295
- | `forge task start --accept "..." --assert "type:arg :: expected"` | v2 结构化断言(spec-as-gate):五型机械可判 `exit`(期望退出码)\|`contains`\|`not-contains`(输出子串/反作弊)\|`file-changed`\|`file-untouched`(glob 对任务 diff——freeze 语义的任务级版,保护对象含 .md/.yml 等非源码);`--assert` 附属于同命令中 preceding `--accept`,file-\* 型可独立出现(无 Run);regex 刻意排除(ReDoS + 不可判——意见不走 hard);声明期拒绝叙述性与越形断言 |
296
- | `forge task start --accept-file <yml>` | 批量考卷声明:顶层 `criteria:`,每条 `run/expected/assertions[type/arg/expected]`(键与任务状态 JSON 一致);与 `--accept` 同层级、按 (Run, Expected, Assertions) 三元组去重合并 |
297
- | `forge eval golden harvest [--since <ref>]` | golden 候选收割(L3):只读扫描本地已完结任务的验收考卷,机械投影成候选骨架落 `evals/forge/golden/candidates/`(gitignore,永不进 VCS)——候选经实跑探测→翻转 kind→人工策展转正 canonical;canonical 目录零写入(guard 钉死,golden 只进人工策展红线) |
298
- | `forge review llm [--scores <file>]` | LLM 判官臂(L3「可命题」类约束的执法通道):无 flag 打印独立只读子代理评审派遣说明(design/mock-hallucination 两类 findings,0-100 判分);`--scores` 校验 JudgeAuditEntry 判分文件落 judge-samples 留档并指向 `forge eval judge-audit` 算 κ(地板 0.6,不达标降级 ADVISORY——判官永不进 hard) |
299
- | `forge task wild "<说明>"` | 野外动作申报:任务管道外的显式留痕出口(比静默绕过诚实、比强制建任务轻)。记会话/分支/HEAD/是否已有任务到 `wild/declarations.jsonl`,累计计数供审计回溯(vNext INV-1 的合法出口之一) |
300
- | `forge task status` | 查看当前任务门禁状态(含已登记产物链产物与漂移/审批态) |
301
- | `forge task list --open [--workspace\|--all-projects] [--json]` | 列出未完成任务供用户挑选要接续哪个:每条带项目、标题、门禁进度、首条下一步、未解决阻塞数、派活状态、最后活动时间。默认当前项目;`--workspace` 扩到当前项目所属多仓 forge workspace 的全部成员(不属于任何 workspace 时回落当前项目);`--all-projects` 扩到本机全部已接管项目。只读 |
302
- | `forge task list --plan-conversion` | plan-first advisory 转化率报告(先测量再翻转):已发/发后已补方案/发后仍无方案/未发自带方案四计数 + 转化率——叙事 stage 是否升档由数据决定而非直觉 |
303
- | `forge task artifact --set <stage> --file <path> \| --stdin \| --list [--json] \| --verify \| --approve <stage> --by <人> [--checked <项>] \| --extract \| --check [--file <path>]` | 产物链操作(L6 契约层,docs/design/artifact-chain-workflow.md):登记阶段产物(哈希引用,漂移探测;登记 design 产物时其「触点」一节自动写入 PlanScope(手工 `--scope` / `task scope add` 优先),实改超出即报「方案外改动」)/ 查看链态 / 漂移校验(采用需求 ID 的任务附需求覆盖表:已验证/未验证/孤儿)/ 人工审批(human 档经 --by 归因到人、签内容哈希,内容再改即作废;批前打印一屏审批摘要——TL;DR、高危步骤、Open Questions、自上次批准的变化;`--checked` 可重复,记录本次审了什么)/ 从产物提取验收标准(`accept: <cmd> :: <expected>` 行与 \`\`\`accept 围栏编译成验收门禁——产物成为硬门禁的源码;提取的标准盖考卷层级 spec-extract;`accept[REQ-3]:` 前缀或行尾 `#REQ-3` 声明该条验证的需求 ID,两种写法并存取并集)/ 方案事实核查 `--check`(方案中的路径、`file:line`、Go 符号、Go 模块是否真实存在;`new:` 行豁免;advisory)。链与档位(advisory\|rubric\|human\|hard,HARD 只守事实)由 `<DataDir>/schemas/schema.yaml` 声明(缺省默认链 proposal→spec→design→plan 全 advisory 零阻断);`task start --artifact "<stage>=<path>"` 开工即登记并就地提取验收;complete 前漂移 pre-flight:hard/human 档漂移阻断、advisory/rubric 留痕、漂移一律作废审批;逃生(落审计)`FORGE_ARTIFACT_CHAIN=disable` 或 `forge task override --artifact-chain disable` |
304
- | `forge task chain-init [--force]` | 一键接线产物链执法(oracle-pipeline L0):写默认链 schema 且 spec 档升 human——spec 里的考卷围栏(accept: 行/```accept 块)从此需 forge task artifact --approve spec --by <审批人> 签字才算定稿,内容再改即作废(业务正确性的签字入口);已存在 schema 须 --force 显式覆盖;不依赖活跃任务 |
305
- | `forge task mine [--agent <agent>] [--role <role>] [--all-projects] [--blocked] [--json]` | 列出分派给当前/指定 agent 的任务(`--all-projects` 全仓扫描按项目分组;`--blocked` 仅被依赖阻塞的,标注卡在哪环 [status, gate 进度 passed/total]) |
306
- | `forge task gate <gate-id>` | 验证单道任务门禁 |
307
- | `forge task impact --level none\|multi [--repo <key>]... [--note <说明>] [--ref <ref>]` | 声明当前任务的跨仓影响(多仓 workspace 成员的 verify 前置,单仓改动也须显式声明):`--level none` 改动限定本仓;`--level multi --repo <key>` 波及指定成员 repo(`--repo` 可重复)。默认 advisory(未声明只提醒),protocol.yml 配 `cross_repo_impact: required` 升级为 HARD stop(四段式 WHAT/WHY/HOW/REF 报错),详见 docs/design/multi-repo-workspace.md |
308
- | `forge task verify-acceptance [--ref <ref>] [--trust-foreign]` | 实跑验收标准(task start --accept 登记),记 deterministic 证据;v2 断言逐条判定并记 `acceptance-assert` 证据行(聚合 `acceptance` 行保留);验收命令来自 task import / .forge migrate(外来标记)时首跑须 `--trust-foreign`(人工审阅命令清单后显式受信,防外来命令串直接执行);登记了 held-out 保留集(`task start --heldout <file>`)时同时实跑双套件并记 gap——可见全过而保留集挂 = test-generalization gap(SpecBench 形态,`FORGE_HELDOUT=disable` 逃生留痕),task-complete 边界复跑;零登记时自动从 conventions 档案兜底登记默认套件(build/test/lint,考卷层级 conventions——项目默认考卷而非实现者自选),并从 held-out 池自动抽 1 套业务坏天气集入卷(池非空时,墙-2b) |
309
- | `forge task accept <criteria...> [--ref <ref>] [--assert "type:arg :: expected"]` | 补登记验收标准(考卷层级 manual——实现者看过代码后出的题,梯子最弱一级):格式同 --accept("run :: expected",可多条),`--assert` 挂本命令最后一条标准(file-\* 可独立);锁内合并按 (Run, Expected, Assertions) 三元组去重(已存在的同一检查保留原层级);已完成任务拒绝补登(考卷在交付前定稿);交付验收单如实披露 manual 层存在 |
310
- | `forge task report [--ref <ref>] [--json]` | 交付验收单(验收方单页视图):考卷逐条结果+层级与来源分布、评分与证据强度(deterministic vs agent-claim)、未验证面(UntestedAreas)、残留风险(完成时 open findings)、考卷披露(manual 层告警/held-out 保留集/spec 审批态)、逃生舱库存、审查轮次——附复现入口(verify-acceptance 重跑 / trace 证据链);逃生债行(价-1a:每个验证类逃生转为未验证面披露)、自供申辩计数(价-1c)、自审标记(价-1b:盖章会话=改动生产者时 doc-gate 不消费自录分);--json 结构化输出 |
311
- | `forge task mutation [--sample N]` | mutation 抽样(oracle-pipeline L2a,机器出题治假绿;作用于当前活跃任务,无 --ref):对任务改动的 Go 源文件注入变异体(比较/逻辑翻转),逐个原地变异→实跑所在包 go test→立即还原——杀不死变异体的测试是装饰品(断言弱化/空断言无论覆盖率多高都查不出)。判定走 go 退出码契约(测试失败=杀灭/构建失败=无效体/通过=存活逐位点点名);确定性均匀抽样(默认 3,硬-1a 提速:只变异磁盘上有配对测试的改动文件,FORGE_MUTATION_TIMEOUT 调单变异体超时);证据落 mutation-sampling deterministic 行(计入证据强度);advisory 不阻断 |
312
- | `forge task fuzz [--sec N] [--max N]` | fuzz 实跑(oracle-pipeline L2b;作用于当前活跃任务,无 --ref):发现任务改动包的 Fuzz 目标并按预算执行 Go 原生引擎(默认 30s/目标、最多 3 个)——edge 清单再全也是人枚举的,fuzz 是无记忆的对抗者;失败目标分型:退出码 1=真 crasher(崩溃输入由 go 写进 testdata/,证据即语料,修完 go test 回归),构建失败/预算中断则无 crasher 语料;证据落 fuzz-run deterministic 行;advisory 不阻断 |
313
- | `forge task edgecheck` | edge case 清单(oracle-pipeline L2c;作用于当前活跃任务,无 --ref):任务改动的每个导出函数 × 五维(基数/值域/时序/环境/故障)机械枚举成可勾选骨架,落 DataDir/edgecases/——机器出骨架、验收前逐项填断言;确定性生成(文件序×声明序) |
314
- | `forge task regression --finding <id> --test <file> \| --none --note <理由>` | 登记 finding 的回归测试绑定(oracle-pipeline L4 修复自证):修前红由 finding 作证、修后绿由 --test 指向的本任务改动 _test.go 作证(三重校验:后缀/任务窗口/真含测试函数);无可测形态走 --none --note 落审计行——`forge task finding --resolve` 的硬前置,没有回归的 fixed 会复发 |
315
- | `forge task heldout-pool --add <file> --name <名> [--tag <组>] \| --list [--tag <组>] \| --draw N [--tag <组>] [--apply] [--ref <任务>]` | held-out 池(oracle-pipeline L3 独立出题):把出保留题变成项目资产——业务坏天气集(金额边界/并发/退款链)沉淀进 DataDir/heldout-pool/,任务侧 `--draw N --apply [--ref <任务>]` 名序确定性抽取并入指定/活跃任务保留集(按 Run 去重、保留集计数不清零、落 apply 审计行;verify-acceptance 实跑双套件记 gap);同名拒绝静默换锚;--add/--list/--draw 是项目级动作不依赖活跃任务;「测试的测试」是人工边界——池里的题必须人出 |
316
- | task-complete 验收登记门禁(自动) | 非 generic 交付任务零验收标准 → 拒绝完成(考卷缺位);考卷质量下限(墙-2a):有测试能力仓库考卷须含 ≥1 条测试类命令——单条 go build 不构成合格考卷;hazard 清账(墙-1b):未确认高危拦截悬账 → 拒绝完成(出口是真人 confirm/release,均需终端 char-device;FORGE_HAZARD_PENDING=disable 留 CI);mutation 复发升硬(硬-1b):Go 改动连续 3 任务零 mutation 证据 → 硬拦(FORGE_MUTATION_GATE=disable 逃生)。考卷层级梯子:spec 产物提取(human 档可签字)> start 登记 > conventions 兜底 > manual 补登(验收单披露)。逃生与 freshness 共用舱:`forge task override --acceptance-gate disable` / `FORGE_ACCEPTANCE_GATE=disable`(落审计、降 evidence) |
317
- | `forge hazard halt status` / `forge hazard halt release --yes` | safe-halt 语义:hazard-guard 连续拦截 ≥3 次(自最近 confirm/release)→ 会话停机(停止自修复盲试,task gate 推进时明示);人工核查最近拦截命令后 `release --yes` 解锁(记 halt-release 审计事件,agent 不得自我解锁) |
318
- | `forge task mirror github [--repo owner/name] [--dry-run]` | 分派任务镜像到 GitHub Issues(Forge 台账为主真相、issue 为组织可见面;offered→建 issue 打 forge:状态 label,终态→关闭;映射存 DataDir/mirror-gh.json;经 gh CLI,无 gh 明确报错)——Symphony 验证的组织面入口需求 |
319
- | `forge compat snapshot [--out <file>]` / `forge compat report [--base <ref>] [--json]` | 可执行兼容工件(七面快照:命令树+flags / CheckName roster / 逃生舱 env / 内嵌载荷 sha256 / 序列化 schema 键 / 阻断位点计数 / 外部桥契约)——golden(compat.snapshot.json)入库、PR diff 呈现;report 对比基线:破坏性变更(removed/changed)exit 2、added 提示同步文档(cargo-semver-checks 契约本地化:0=过 / 2=违规 / 1=工具故障);承诺表见 docs/design/compat-commitments.md |
320
- | `forge config get/set compat <版本>` | 兼容基线声明(指纹分流 v1,GODEBUG go 行声明的轻量版):声明"行为按哪个版本的默认走"(v1 为声明性锚点 + 落后提醒,暂不分派行为——完整分流机制见承诺表"刻意不做");`forge status` 显示兼容基线行与落后 minor 数;遥测回读(逃生舱使用聚合)见 `forge eval dashboard` |
321
- | `forge task watchdog [--stall 45m] [--release]` | 长时任务停滞检测(always-on 治理):从 checklog/toollog 取未完成任务的最后活动,超阈报停滞(task-stalled advisory,marker 节流每小时一条);`--release` 清停滞任务租约;顺带展示 token 熔断信号 |
322
- | `forge task doc-review --passed <pass\|fail> --score <N> [--round <R>] [--reviewer <id>] [--critical <tag:发现>] [--co-reviewer <id> --co-score <N>]` | 记录 L2 文档回检证据(输出→回检循环):按 doc-review skill 四维评审后落档(产出者不能自检);`--score` 为 0-100 总分、`--round` 轮次(≥3 轮未过升级人工确认)、`--critical` 落 Critical findings(未决阻断 complete;`tag:` 前缀打标供进化判据聚合)、`--co-reviewer/--co-score` 落同家族 borderline 双评记录(gate 不消费,只作分歧率观测)。task-complete 的 doc gate 消费该证据 |
323
- | `forge task finding --content <text> [--tag <枚举>] \| --resolve <id> \| --stats [--source <source>]` | 记录发现/标 fixed/跨任务聚合:`--tag` 打类别标(padding/conclusion/template/false-precision/disclaimer/evidence/style);`--stats --source doc-review` 按 Tag×Round 跨任务聚合计数——session-retrospective「同类打回 ≥3 次」升级判据的机器来源 |
324
- | task-complete 自报一致性门禁(自动) | checklist 已勾选项里声称执行过的验证类命令(go test/pytest/cargo test 等)与 toollog 实测 Bash 集比对:测试类声称任务全程零匹配 = 虚报进度形态(arXiv 2605.29442)→ 拒绝完成;非测试类差集只留 advisory 痕;toollog 缺失(宿主遥测未接)跳过——区分"无法验证"与"验证通过";逃生(留痕)`FORGE_SELF_REPORT=disable` |
325
- | `forge docs lint [paths...] [--base <rev>]` | 文档产物 L1 确定性 lint(D1-D11:禁令短语/无证据结论/复述 diff/通过断言无证据/必填章节/结论枚举/篇幅/结论位置/调研文档的来源、信度标注与内部标签——调研三条 D9-D11 在观察期内全是 advisory);`--base` 改扫该基线以来变更的 .md。exit code:0=通过 2=硬失败。禁令清单单一真相源在 `internal/doclint`,同步渲染进 forge-quality skill |
326
- | `forge eval card [--render]` | 治理披露卡:Forge 占 ETCSOVG 哪四层、hook/门禁/逃生舱清单与已知盲区(缺节 BLOCKED)。评测体系:docs/design/forge-evaluation-system.md |
327
- | `forge eval dead-checks [--window 90d] [--json]` | W0.1 死检查报告:聚合 checklog+hazard 台账,按检查分 live / dead-candidate / insufficient-data(hook 瘦身的数据面;嵌入式 hook 的 PASS 不逐次落账,触发率为下界——输出内明示) |
328
- | `forge eval friction [--corpus <dir>] [--timeout 120s] [--json]` | W2 摩擦净值实验(脚本化双臂):诱饵语料在「门禁开 / 既有逃生舱全开」两臂下实跑,量拦截率、残余与检查器开销(ON-OFF 墙钟);端到端 agent 臂走 FORGE_EVAL_MODEL 通道 |
329
- | `forge eval rule-ledger --record --rule <id> --claim <预测> --probe <命令>` / `--verify --rule <id>` / `--list` | W5 门禁规则可证伪台账:规则变更带预测声明 + 可执行 probe,verify 实跑落账结论(`evals/rule-ledger.jsonl` 随库提交;损坏行 fail-closed) |
330
- | `forge init --profile <lite\|standard\|full>` | W0.3 接线档位:lite=拦截+管线+状态最小集(12 hook/6 事件),standard=完整现行(默认),full=预留位;持久化 `~/.forge/profile`,FORGE_PROFILE env 可覆盖,运行时门即时生效 |
331
- | `forge eval dashboard [--dry-run] [--json]` | Track B 遥测(C4/C7):escape 率/off_churn/自举通过率(Wilson 95% CI + 误用注记;样本低于字典下限只出 INSUFFICIENT)。快照落 `~/.forge/evals/forge/snapshots/` |
332
- | `forge eval harness-audit [--json]` | A–G harness 修复的事前/事后度量(docs/design/harness-fixes-a-g-2026-09.md M):checklog × toollog(2s 双记去重)× 任务 × hazard 一次算出 skill-trigger 日均触发/按通道转化/inline 跟随/verification-driver 精度、next-hint 采纳、门禁命令形态 C1–C3、refs-critical 下钻(按 host)、封印后归因泄漏、hazard 双投递、coverage 拦后转 pass;`--json` 带口径字段,两机回测只比同口径基线(`evals/harness-audit-*-baseline-*.json`) |
333
- | `forge eval golden run [--dir <dir>] [--repeats N] [--rewrite-manifest] [--release] [--json]` | 门禁 golden 标注集重放:precision/fpr(Wilson 区间)+ 确定性重放一致率;用例集指纹钉在 `evals/forge/golden/MANIFEST.sha256`,不符拒绝运行(`--rewrite-manifest` 仅限显式轮换)。用例 `layer: test` 只在 `--release` 时运行,每次给 test 层查询计数 +1 并落 `eval-golden-test-query` 行 |
334
- | `forge eval golden private-init` / `rotate [--max-cases N]` | 私有 golden 子集(0700,永不进 VCS)与季度轮换(oracle 复验 + 最老优先淘汰 + 审计行) |
335
- | `forge eval traps run [--dir <dir>]` | 对抗陷阱重放(14 用例:测试削弱/伪造审计证据/虚假完成 + cheat-scan 七模式族 11 例——type-suppression/error-swallow/dead-branch/comment-only-fix/comment-as-debt/phantom-import/path-assumption,经 gate push --dry-run 推送边界探测;ImpossibleBench 思想);capture 率与行动清单 |
336
- | `forge eval redteam` | seeded-bug 红队演练(oracle-pipeline L6):对验证链自身注入五类雷(零验收交付/internal 零引用导出/吞错/类型抑制/heldout gap),逐颗用既有检查函数判定拦截——escaped 或设施故障即如实披露(exit 非 0 供 CI 门禁);与 traps 互补:traps 回放过去,redteam 注入现在 |
337
- | `forge eval oracle run [--suite evals/oracle] [--arm both\|scanner\|acceptance] [--repeats N] [--image <img>] [--json] [--out <md>]` | 变更级沙箱考卷(v0,docs/design/sandbox-oracle.md):每条用例在临时 git 仓库里回放一次变更——扫描臂调与被测门禁同一函数 `ScanCheatPatternsRange` 量 cheat 召回/类别准确率/误报(known_fp 不进分母),验收臂在 `docker run --network none` 里先跑可见测试(OFF)再挂 held-out(ON)量逃逸率;套件指纹(用例 sha256)写进报告可复算,`--repeats` 检出确定性漂移(flips)。实测 v0:召回 86%(6/7,唯一漏网是无机械签名的语义 stub——盲区被记录而非漏测)、误报 0/3、逃逸 100%→0% |
338
- | `forge eval judge-audit --scores <file>` | 判分器受审:重放极差 + 与人工标注 Cohen's κ;κ<0.6 该判分器 BLOCKED 决策降级 ADVISORY。分数可带 `pair_original`/`pair_swapped`(a\|b\|tie)做成对位置交换审计,翻转率 >10% 判 high systematic bias |
339
- | `forge eval resume-drill [--dir <dir>]` | 接续演练(C3):脚本化断点续做断言(仅回归对比,绝对值不外宣) |
340
- | `forge eval run --manifest <file> --profile <off\|gates-only\|full> --model <m> [--repeats N] [--wallclock <d>] [--forge-ref <ref>] [--variants a,b,c]` | Track A 端到端基准运行(四元组 scorecard + pass^k 曲线 + 预算截断披露;`--forge-ref` 标注被测 forge 版本,四元组之一);真实执行需 `FORGE_EVAL_SMOKE=1`,否则确定性 scripted 替身。开跑前 preflight:带 `test_cmd` 的容器任务须声明 `oracle_cmd`,oracle 臂须全过、只跑判分的 do-nothing 臂须全败,否则 BLOCKED exit 2(`FORGE_EVAL_PREFLIGHT=skip` 逃生,证据封顶 Weak);`leakage_cmd` 声明时 leakage 分数与 pass@1 并列,高分任务列入需复核。`--variants` 声明 ≥3 个语义等价 prompt 变体时计入 CI 的扰动方差源 |
341
- | `forge eval decompose --manifest <file> --models <a,b> [--profiles off,gates-only,full] [--repeats N] [--variants a,b,c]` | 方差分解大体检:HV̄/MV̄ + 排名翻转数 + η²_p + 三档差值(full−off 整体贡献 / full−gates-only 注入层 / gates-only−off 纯门禁代价);三档差值带分层 bootstrap 95% CI,跨零时固定表述「在 n=X 次运行下未检测到显著差异;最小可检测效应 Y pp」 |
342
- | `forge eval report [--quarter 2026-Q3]` | 季度自评测报告(汇编已落盘证据;缺失如实标注,绝不补造) |
343
- | `forge eval otel [--out <file>] [--limit N]` | checklog → OTLP/JSON 导出(OpenTelemetry 通道:审计行进企业 SIEM/APM;scope=forge.checklog versioned mapper,`--limit` 只导最新 N 条) |
344
- | `forge eval aat [--out <file>] [--limit N]` | checklog → IETF agent-audit-trail 形状 JSONL(链式 prev_hash + trust_level L0-L3;versioned mapper,meta 头声明全部有意偏离——标准卡位,见 docs/compliance/standards-crosswalk.md) |
345
- | `forge skills inventory [--lock\|--verify] [--json]` | AST10 对齐的 skill 清单与内容指纹:枚举 canonical + pack 树、每个 SKILL.md 的 sha256;`--lock` 钉基线(skills-inventory.lock 提交进仓),`--verify` 对照锁文件核对(漂移/未知/缺项 exit 2——OWASP AST07 "immutable pinning, hash verification" 机械落地) |
346
- | `forge gate push [--ref <branch>] [--dry-run]` | git 推送边界门禁:merge-base...HEAD 重跑确定性 cheat-scan + 本分支未消解 BLOCKED 任务(不依赖本地 hook 是否生效——云端 agent 分支同受治理);证据快照落 DataDir/pushes/,CI 里复跑同套判定兜底;阻断 exit 2 |
347
- | `forge gate hooks install [--uninstall]` | 安装 git pre-push 钩子(core.hooksPath=.forge/git-hooks,调 `forge gate push`;forge 不在 PATH 时 fail-open 放行)——治理随 git 走的本地接线 |
348
- | `forge task scope add <glob> [--ref <ref>]` | 追加计划改动文件到白名单(支持中途迭代;--ref 指定任务,不依赖活跃任务检测) |
349
- | `forge task scope show` | 查看声明的白名单 + 实时 scope-drift(advisory,不阻塞) |
350
- | `forge task override [--work-activity\|--test-coverage\|--acceptance-gate\|--skill-decisions\|--doc-gate] disable` | per-task 逃生舱:关闭指定门禁检查(如批量重构时关 read-before-edit);使用落 checklog 审计。验证类(test-coverage/acceptance-gate/skill-decisions/doc-gate)evidence 强度 cap 到 Weak(重证据任务按证据缩放豁免);work-activity 是节奏门禁,只审计不降强度。doc-gate 的放行须在 doc-review 轮次上限后经人工确认再走 |
351
- | `forge task complete` | 标记任务完成(自动评分) |
352
- | `forge task abort [--ref <ref>] [--cascade\|--detach-deps]` | 中止并删除任务(清理 ghost/卡住任务,不评分;存在反向依赖时默认仅提示,`--cascade` 递归中止所有依赖它的任务,`--detach-deps` 从依赖它的任务移除该依赖边) |
353
- | `forge task score` | 查看任务质量评分 |
354
- | `forge task resume [--ref <ref>]` | 拉回任务接续上下文(目标/计划/决策/阻塞/参与工具+门禁进度+git 已改),跨会话/跨工具秒级恢复;同时把当前 session 锚定到任务(未 resume 就直接改代码的 session 由 task-guard 在首次源码写入时静默补锚) |
355
- | `forge task resume --match "<关键词>" [--workspace\|--all-projects] [--json]` | 模糊匹配未完成任务(ref/标题/分支/目标;容忍错拼、乱序词、缩写、中文片段),返回至多 10 个带得分的候选。只读:不锚定、不认领——agent 让用户确认后再 `resume --ref` 接手 |
356
- | `forge task context [--ref <ref>]` | 只读查看接续上下文(resume 的不改 state 别名) |
357
- | `forge task decide --content` | 记录已确认决策(持久化进 task,跨会话/跨工具不再推翻) |
358
- | `forge task decide --rejected --content --rationale` | 记一条已证伪方案(死路记忆,docs/plans/loop-contract-2026-10-proposal.md):`--content` 写方案、`--rationale` 写失败证据;resume 单独成节【已证伪方案】并进 tl;dr,不列入已确认决策。验收同因复发时 forge 会自动记一条 |
359
- | `forge task next <step>` | 追加下一步(可多条) |
360
- | `forge task block --content/--resolve <id>` | 登记阻塞或解决阻塞(open→resolved) |
361
- | `forge task finding --content/--resolve <id>` \| `--reset-loop --note` | 记录跨工具发现(带来源工具)、标 fixed(指纹入 ResolvedPrints 记忆);**审查回环**(回边语义,docs/design/artifact-chain-workflow.md):open finding 跨过 schema 回边 max_rounds 次复核、或已解决 finding 同指纹再登记(复活)→ 回环耗尽,complete 被拦升级人工;人工裁决 `--reset-loop --note` 重开(审计行落地)。耗尽后唯一出口是人——终止权外置 |
362
- | `forge task attach --ref --tool` | 锚定 session+工具到 task(跨工具多向锚定:pi 起、claude-code 接) |
363
- | `forge task assign --ref <ref> --to <agent> [--role] [--by]` | 把任务分派给指定 agent(offered 起步,编排器侧;未知 agent 警告但接受) |
364
- | `forge task claim --ref <ref> [--as <agent>]` | 工作方认领分派给自己的任务(offered→claimed,自动锚定 session) |
365
- | `forge task deliver --ref <ref> [--as <agent>]` | 工作方交付任务(claimed→delivered,交回编排器;--as 与 claim 对齐,与分派 agent 不符仅提醒不阻断) |
366
- | `forge task question --ref <ref> --content <text>` | 工作方回抛问题(claimed→input-required,暂停等编排器/人答复) |
367
- | `forge task answer --ref <ref> [--content <text>]` | 编排器答复回抛(input-required→claimed,答复记入 Decisions;空答复仅恢复 claimed) |
368
- | `forge task fail --ref <ref> --reason <text>` | 工作方标记任务失败(claimed→failed,记录原因) |
369
- | `forge task cancel --ref <ref> --reason <text>` | 编排器撤回分派(offered/claimed/input-required→canceled,记录原因) |
370
- | `forge task reopen --ref <ref> --reason <text>` | 交付后重开(delivered→claimed,交付后发现 bug) |
371
- | `forge task reclaim [--dry-run] [--json]` | 回收 claimed 僵尸任务(claimed>TTL 默认 7d 无 checklog 活动)回 offered、重置认领时钟(补齐设计 §3 TTL 回收触发;复用 task health 的 IsClaimedStale 同一真相源,故 health 报告与本命令目标永远一致)。回收保留 Agent 不变 → 只有原认领 agent 崩溃/重启后能重新认领;改派用 cancel+assign。`--dry-run` 只列出不改状态 |
372
- | `forge task export --ref <ref> [-o\|--output file] [--include-checklog] [--redact]` | 把任务导出为跨机器 JSON Bundle(task state 存于用户级 DataDir 不随仓库走,跨机器交接需此载体;--include-checklog 附带证据链;--redact 抹除 issue/agent/commit/证据供对外分享) |
373
- | `forge task import --file <bundle> [--force\|--merge]` | 从 Bundle 导入任务到本地(导入 session 标记幽灵仅溯源;默认同 ref 拒绝,--force 覆盖,--merge 按 ID 并集协作记录;含 checklog 则回放进本地 trace) |
374
- | `forge task health [--json]` | 扫描全 project 上浮僵尸/死锁/长期未答复任务(只读告警,不改状态):offered>7d / claimed>TTL(无 checklog 活动)/ input-required>7d / abandoned_count≥2 标黄,DependsOn 指向 failed/canceled/缺失的死锁链与环主动报;与 mine/看板共享同一检测真相源 |
375
- | `forge selfcheck pairing` / `forge selfcheck scope` | 门禁镜像自检(discipline-first-gates):对当前活跃任务跑与 task-verify **同一计算路径**的秒级自检——`pairing` 镜像 test-coverage 配对检查、`scope` 镜像 PlanScope 漂移;发现项逐文件列出 + 修复指引(exit 1 供脚本感知,非阻断),每次运行落 `selfcheck-pairing`/`selfcheck-scope` 观察条目——其后失败的 verify 门禁按事实级交集归 confirmation(agent 已被告知这批文件)而非 discovery。逃生激活时显式标注「门禁已豁免、以下为事实」。`forge next` 在验收待跑且未自检时提示先行自检 |
376
-
377
- </details>
378
-
379
- <details>
380
- <summary><b>🔍 代码审查 / 高危命令 / Act 反馈(自动挡)</b></summary>
381
-
382
- **代码审查门禁**:`forge review` 让 code-review-gate 从"靠手动唤起"变成自动挡——task 流程下 task-complete 门禁强制 ReviewPassed 前置(提交前必审);非 task 流程下 Stop hook 自动拦截未审的源码变更。误触发已防护:纯文档/配置/生成物变更、无变更、commit 后干净工作区不触发;同一 diff 反复未审最多 block 3 次后 advisory 放行(防 Stop 死循环)。审查由独立只读子 agent 执行(防自审盲区),见 `code-review-gate` skill。
383
-
384
- | 命令 | 说明 |
385
- |------|------|
386
- | `forge review pass [--ref <ref>] [--note <文本>] [--acknowledge-changes]` | 标记当前变更已通过 code-review-gate(task 模式写任务状态,否则写分支 stamp);--note 审查结论文本记入 ReviewRound/stamp 与 checklog 审计留痕;距上次基线有源码变更时裸 pass 会被拒——须 --note 记复审结论,或 --acknowledge-changes 显式自我承担(记 WARN 级 self-refresh 审计) |
387
- | `forge review gate` | 判定当前是否需要审查(Stop hook 调用;exit 0=放行,1=需审 block) |
388
- | `forge review status` | 显示当前审查状态 |
389
- | `forge enforcement [--sample N] [--json]` | 执法健康报告(只读聚合 checklog+会话 markers+野外申报):task-guard advisory/blocked 计数、无视升档会话、缓冲窗口超时违规(升档后 3 次编辑窗口内未补救——建任务或 wild 申报——则落违规记录)、无任务测试编辑、wild 申报数;双环信号(升档超阈→审查规则本身而非加码执法)与降格信号(提升规则零阻断零升档→zombie rule 复审)。`--sample N` 随机抽已完成任务 join 其会话遥测——"无视升档仍完成且未被阻断"样本标强制复盘(无灾≠安全);随机化使审计不可预演 |
390
-
391
- **高危命令 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 --last` 登记 5min 限时标记(agent 自行运行会被拒)→ 重试放行。阻断但放行权在人,而非无条件硬 block:合法高危操作(删 build 产物)确认后能继续;`FORGE_ALLOW_HAZARD` env 豁免已移除(可被 agent 自我放行滥用),confirm 链是唯一放行路径。
392
-
393
- | 命令 | 说明 |
394
- |------|------|
395
- | `forge hazard confirm --last` | 确认最近一条被拦命令(从事件日志取指纹,零复制转写,推荐;须真人终端) |
396
- | `forge hazard confirm <命令> [--fingerprint <hex>]` | 登记一次高危命令确认(5min 内同命令重试放行;`--fingerprint` 回传 hook 输出的 hex 指纹;须真人终端) |
397
- | `forge hazard status` | 列出当前有效确认及剩余时间 |
398
-
399
- **写入范围冻结**:`forge freeze` 把 on-demand-guards 的 /freeze 目录锁定从「agent 每回合自检」的 prompt 型护栏落地为真 hook——激活后 freeze-guard hook(PreToolUse Write|Edit,排在 task-guard 之前优先判定)硬阻断所有冻结路径之外的写入,长会话/压缩后不漂移。支持多路径、相对路径(相对当前目录归一化)、Windows 大小写不敏感比较。
400
-
401
- | 命令 | 说明 |
402
- |------|------|
403
- | `forge freeze <路径>...` | 激活 freeze(可多路径;再次激活即替换范围) |
404
- | `forge freeze --off` | 解除 freeze(幂等) |
405
- | `forge freeze --status` | 查看当前 freeze 状态 |
406
-
407
- **Act 反馈臂(证据驱动结论)**:`forge task complete` 时把本任务的证据驱动结论(评分 + 证据强度 + 验收通过率 + 低分维度)落盘到 `~/.forge/projects/<项目key>/act/conclusions.jsonl`,喂给 `session-retrospective`。证据弱(Unverified/Weak)或低分(<70)的结论标 RetrospectiveNudge——对冲"高分但没真验证"的 LLM-judge 盲区。
408
-
409
- | 命令 | 说明 |
410
- |------|------|
411
- | `forge act show [--ref <ref>]` | 查看最新(或指定)任务结论(含 skill 触达画像——该 task 期间触发了哪些 skill) |
412
- | `forge act list [--json]` | 列出所有任务结论 |
413
- | `forge act nudge` | 最新结论有回顾 nudge 时输出一行(否则静默)——供 task-verify 会话结束 hook 消费 |
414
- | `forge act retro-done --ref <ref> --carrier <memory/skill/claudemd/code/hook/ci/none> [--lesson <教训>]` | 证据式 ack:session-retrospective 沉淀完经验后记录「回顾已发生」,被 ack 的 nudge 退出面板告警(`--lesson` 一句话教训;忘调用则 nudge 留面板——错过的回顾可见) |
415
- | `forge act rebuild` | 从 tasks/*.json 重建 conclusions.jsonl(迁移 act 上线前的旧任务) |
416
-
417
- </details>
418
-
419
- <details>
420
- <summary><b>🧠 Skill 治理</b></summary>
421
-
422
- 分发内置 canonical skill 库到各 coding agent,并守护 skill 质量(规范 + 安全)。
423
-
424
- | 命令 | 说明 |
425
- |------|------|
426
- | `forge skills install` | 分发 skill 到全局/项目目标目录(link/copy) |
427
- | `forge skills list` | 列出 canonical skill 库中的 skill |
428
- | `forge skills audit` | 21 条安全规则审查(prompt 注入/数据外发/危险代码/供应链执行向量;任一 CRITICAL finding 即阻断 install/--gate) |
429
- | `forge skills drift-check` | 检测分发分叉(dry-run,不写);另报其他已安装 Claude Code 插件里与核心同名的 skill(plugin-shadow;forge 插件提示升级去重,第三方插件提示停用其一) |
430
- | `forge skills validate` | R1-R18 规范校验 |
431
- | `forge skills adapters` | 部署 skill-routing adapter(pi/claude/cursor/routes.json) |
432
- | `forge skills usage` | 使用度量分析(热门 skill + undertrigger 候选) |
433
- | `forge skills usage --by-keyword` | per-keyword 触发分析:命中/加载/抑制切片(v2 Meta 的 matched_keyword)+ 死关键词检测(声明未命中;窗口无 v2 证据条目时自动停用并说明)。加载列带宿主偏差标注(注入型宿主无工具事件信号) |
434
- | `forge skills effectiveness` | 技能命中×任务成效关联(命中数/task数/avg分/弱占比,agent-neutral) |
435
- | `forge skills --dir <path>` | eval 命令族公共 flag:指定 eval 数据目录(默认 `~/.forge/evals`,`FORGE_EVAL_DIR` 可覆盖;首次默认解析自动从旧 `~/.pi/research/skill-eval` 一次性迁移。仓库内 `evals/` 或 CI 用) |
436
- | `forge skills eval-gen [--save] [--cases-only]` | 生成 eval 清单;`--save`/`--cases-only` 额外落结构化 case 集(回归闭环基准) |
437
- | `forge skills eval-cases --skill X [--blind]` | 输出 case 集 JSON(agent dispatch 跑 prompt 的输入);`--blind` 盲测模式:每条 prompt 前置全库 name+description 清单(各截断 200 rune,渐进披露 L1 模拟),问「该触发哪个」而非「是否触发 X」,actual ≠ target 的行即误路由混淆数据 |
438
- | `forge skills eval-record --skill X --from <file/->` | 回填一次 eval run(agent dispatch 跑完每个 prompt 后整批提交,归一化+判定+算 health) |
439
- | `forge skills eval-report --skill X` | latest run vs baseline 回归报告(regression 三态 + pass-rate delta + 可比性) |
440
- | `forge skills eval-baseline --skill X` | 标记 baseline run(回归基准,显式人工决策) |
441
- | `evals/golden/<skill>/cases.json`(数据约定,非命令) | 人工策展黄金 case 集(真实话语改写,非 description 派生;进 VCS 可评审)。eval-cases/eval-record 加载时 golden 优先、派生补充,同 ID golden 胜出;策展 ID 前缀 `g-`,`origin: "curated"`,不带 desc_hash(description 变更不过期) |
442
- | `forge skills battery [--gate]` | 全库回归电池:逐 skill latest vs baseline 判回归(JudgeSkillAccept 单一判源),`--gate` 任一回归即阻断(exit 4);无 baseline/陈旧锚点降级 advisory |
443
- | `forge skills mutex-gen` | 生成跨 skill 互斥 case 集(从 description SKIP 段的(用 X)让渡边派生:B 域 prompt 必须路由到 B、不得路由回声明让渡的 A;落盘 mutex/cases.json) |
444
- | `forge skills mutex-record --from <file/->` | 回填一次互斥集 run(actual==Positive 才 pass;`--agent-model`/`--forge-version` 盖章防跨模型/版本假回归) |
445
- | `forge skills mutex-report [--gate] [--json]` | 互斥集混淆矩阵(actual==Negative 为头号混淆行;`--gate` 任一混淆即 BLOCKED(stderr)+exit 4) |
446
- | `forge skills decide [<skill>] --diagnosis ... --prediction <p> --warrant <k:v>` | 记录 skill 决策四元组(skill 名可用位置参数或 --skill;在带 skills/ 树的仓库内默认写仓库 canonical 而非 embed 缓存);`--prediction` 声明可检验预测(哪个可观测信号应改善),供验证闭环回扣;`--warrant` 给出可核验的理由锚点(`run:<eval-run-id>` 与 baseline 有效比对无回归为强,`commit:<sha>` / `doc:<仓库内路径>` 为弱);accept 决策缺锚点、或任一决策的锚点核验失败 / run 回归时 advisory 告警,决策照常记录;每次核验在 forge 项目内落 checklog `decision-warrant` 行(强为 pass、其余 warn)。`--evidence` / `--rationale` 含百分比、倍数或 arXiv 编号(不论内外)时落 `decision-evidence` 行:有来源(URL、正文引用 `run-<id>`,或 `--warrant run:`)为 pass,缺来源为 warn 并 advisory 告警 |
447
- | `forge skills verify --skill X --decision <id> --result <r>` | 回填决策验证结果(预测→验证闭环第二步;`--at` 指定时间、`--history`/`--history-json` 查全量可证伪台账) |
448
- | `forge skills revert --skill X --decision <id> [--edit] [--dry-run]` | Scoped revert:按 decisions.md 的 CommitHash 撤销某条决策关联的 commit(决策闭环的撤销臂) |
449
- | `forge skills integration [<skill>]` | 查看 skill 的 forge 集成笔记(零反向依赖契约的 forge 侧承接:命令语法/门禁/逃生口;无参数列出有笔记的 skill) |
154
+ 活跃任务内,Agent 无法通过 `node -e "fs.writeFileSync()"`、`cat > file`、直接编辑 task JSON 等方式绕过——bash-guard 拦截工具层,file-sentinel 监控文件层,task-guard 保护配置层。**没有活跃任务时 task-guard 只给 WARN 提示,不是硬墙**;有任务才按门禁语义拦截。
450
155
 
451
- </details>
452
-
453
- <details>
454
- <summary><b>📊 可观测与维护</b></summary>
455
-
456
- | 命令 | 说明 |
457
- |------|------|
458
- | `forge health [--json]` | 项目级质量趋势——聚合所有任务结论(分数走势/证据盲区率/复发低分维度,task→project 粒度联动) |
459
- | `forge doctor [--json]` | 跨 agent 环境一致性审计(只读)——扫 9 个 agent host 的 forge hook 接线、解析各 host hook 实际调用的 forge 二进制并对照版本(ok/drift/nover/missing 四态),并列出 PATH 上全部 forge 可执行文件(多个并存 = 游离 exe/shim 抢路,PATHEXT 事故形状);并审计 skills 分发态(canonical vs 全局各目标,missing/drift 附修复命令——canonical 新增 skill 后未重装的目标缺失即在此暴露);copilot 无稳定配置路径约定,刻意不在列 |
460
- | `forge trace <task-ref> [--window <chars>]` | 查看任务的完整质量事件时间线(checklog + toollog + token);`--window` 输出分段监控窗口(每窗 ≤ 预算字符、头部周期性守卫重注入——下游 LLM judge/取证按窗取输入,禁止全量轨迹塞上下文,Classifier Context Rot 缓解) |
461
- | `forge dashboard [--port <n>] [--no-open]` | 本地全局质量看板(Pulse 面板)——在任意目录运行都聚合 `~/.forge/projects.json` 登记的全部项目(`forge init` 自登记),渲染事件流(任务/gate/skill 触发/结论)、任务评分与证据链、skills 聚合(localhost 只读,自动开浏览器,Ctrl+C 退出,面板内按项目过滤);项目目录被移走/删除后注册表条目自动淡出(读时惰性精简),不留幽灵路径 |
462
- | `forge sync [--force]` | 同步 forge 资产到当前二进制版本(用户级 hooks/指令/skill 重生成 + 存量项目级残留收敛;注意:名字易误读——跨机器迁移项目数据用 `forge project export/import`,与本命令无关) |
463
- | `forge plugin pack [--out <dir>]` | 生成多 host plugin pack(.claude-plugin/.cursor-plugin marketplace + plugins/\<name\>/ 树:claude manifest + reasonix native manifest + 每 host 安装 README),让各 agent 一键 `plugin install forge` 跨工具接线(薄 manifest + 共享内容,单仓即 marketplace) |
464
- | `forge bridge verify <dir> [--json]` | 对一个 dsh 插件包跑静态检查(#1884 四大事故模式:inject 一致性 / 同名注册 / @deepseek-ai vendored 耦合 / 未知事件),error → exit 2——dsh 插件作者发布前自检用(roadmap H2a,见 docs/design/forge-dsh-provider-roadmap.md) |
465
- | `forge plugin status` | 报告 forge plugin 是否在 user-level 已装(exit 0=已装,非零=未装;供 init-suggest hook / 脚本检测) |
466
- | `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 始终保留文件壳(绝不删用户全局配置);手动不传则项目级清完删空文件 |
467
- | `forge plugin kimi-manifest [--write]` | 渲染/再生成已提交的 kimi plugin manifest(`.kimi-plugin/plugin.json`)——version 读 `npm/package.json`(单一真相源)、hooks 从 ForgeHookSpec 派生、description 与守卫测试共享常量;默认打印 + 报漂移(退出码恒 0,执法归 `TestKimiPluginManifestMirrorsSpec`),`--write` 逐字节比对后重写(in sync 不改写);forge 仓库维护命令(从 cwd 向上找 `npm/package.json`) |
468
-
469
- </details>
156
+ 27 个内置 Hook 的完整清单(触发时机、职责;可关闭的门禁类都附了逃生开关)见 [docs/reference/hooks.md](docs/reference/hooks.md)。
470
157
 
471
158
  ## 📦 安装
472
159
 
@@ -480,14 +167,7 @@ npm install -g @agent_forge/forge
480
167
  # 支持平台:macOS (x86_64/ARM64)、Linux (x86_64/ARM64)、Windows (x86_64)
481
168
  ```
482
169
 
483
- > **「plugin」一词在 Forge 语境里有两层含义,勿混淆**(设计共识见
484
- > [docs/design/plugin-philosophy.md](docs/design/plugin-philosophy.md)):
485
- > **Forge 的 plugin** = 宿主接线**打包**(分发层)——`plugins/forge`(Claude
486
- > marketplace pack)与 `plugins/forge-dsh`(dsh 桥)这类"薄 manifest + 共享
487
- > payload",宿主 agent 加载它们,Forge 二进制自身不加载任何运行时插件;
488
- > **dsh/Cordis 的 plugin** = 运行时可装卸的**扩展组件**(运行时层)。同名不同物,
489
- > `plugins/forge-dsh` 恰好横跨两者——它以 Cordis 插件的形态被 dsh 运行时加载,
490
- > 本体却只是 forge CLI 的接线包。
170
+ > 「plugin」在 Forge 语境指**宿主接线打包**(分发层,`plugins/forge` / `plugins/forge-dsh`),与 dsh/Cordis 的运行时插件同名不同物——辨析见 [plugin-philosophy.md](docs/design/plugin-philosophy.md)。
491
171
 
492
172
  <details>
493
173
  <summary><b>📖 通过 Claude Code plugin marketplace(用户级,一次性接线)</b></summary>
@@ -499,7 +179,7 @@ npm install -g @agent_forge/forge
499
179
  /plugin install forge@forge
500
180
  ```
501
181
 
502
- 仍需 `npm install -g @agent_forge/forge` 装二进制(hooks 都 spawn forge)。项目登记按 takeover 偏好(P2 起出厂默认 **ask**):init-suggest SessionStart hook 在未接管项目首次会话**询问一次**(同意→`forge init`;拒绝→`forge off`);要"装好即用"的无感体验→`forge config set` takeover 为 auto(静默接管所有 git 项目;declined、`.forge-decline` 团队声明与外来 harness 让位仍然生效;v1.22 起零项目写入——协议与 runtime state 全在用户级 `~/.forge/projects/<key>/`)。hooks 由 plugin.json 全机器接管,`forge init` 跳过自己的 settings.json 注册;存量老项目残留的旧版项目级写入(`.forge/hooks/`、`.claude/settings.local.json` 的 forge hooks、CLAUDE.md/AGENTS.md 的 forge 段)由 autoSync 与 init-suggest SessionStart hook 自动收敛。完整三步与各 host 差异见 `plugins/forge/README.md`。
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`。
503
183
 
504
184
  </details>
505
185
 
@@ -510,7 +190,9 @@ npm install -g @agent_forge/forge
510
190
  1. **门禁先行** —— 任何源码变更走 `forge task` 三门禁(implement → verify → complete),不经任务的改动不被质量评分追踪。
511
191
  2. **注释双语** —— Go godoc 采用形式 A(英文段 → 空 `//` → 中文段),中文不删、不单语;行内注释与字符串字面量不动。
512
192
  3. **审查闭环** —— 提交前派独立只读子 agent 跑 code-review-gate 双轨(AI 作弊 + 工程规范),`forge review pass` 标记后才能过 task-complete 门禁。
513
- 4. **提交纪律** —— 只提交源码变更;排除 `docs/`、设计文档、`.claude/`、`.forge/` 工作目录。
193
+ 4. **提交纪律** —— 提交源码与手维护文档(`docs/reference/` 下的参考文档是测试硬依赖,
194
+ 缺文件整包测试直接红,必须入库;`docs/design/` 属设计文档,同样随代码提交);排除
195
+ `.claude/`、`.forge/` 等生成物与临时工作目录。
514
196
 
515
197
  详见质量协议(由 `forge init` 生成到用户级 `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md`;生成器源码在 `internal/skillgen/`)。
516
198
 
@@ -518,6 +200,9 @@ npm install -g @agent_forge/forge
518
200
 
519
201
  | 文档 | 说明 |
520
202
  |------|------|
203
+ | [完整命令参考](docs/reference/cli.md) | 每个命令、flag、逃生舱与门禁语义 |
204
+ | [Hook 完整清单](docs/reference/hooks.md) | 27 个内置 Hook 的触发时机与职责 |
205
+ | [定位与设计依据](docs/design/positioning.md) | 为什么是确定性门禁而不是模型自检 |
521
206
  | [中文使用指南](READMEs/README.zh-CN.md) | 面向国内用户的安装 / 日常 / 多宿主精简指南 |
522
207
  | [Plugin 安装详解](plugins/forge/README.md) | 多 host plugin marketplace 三步接线与各 host 差异 |
523
208
  | [项目主页](homepage/index.md) | 一分钟简介 + 核心能力速览 |
package/bin/forge CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent_forge/forge-darwin-x64",
3
- "version": "1.84.0",
3
+ "version": "1.84.2",
4
4
  "description": "Forge native binary for darwin-x64. Auto-installed via optionalDependencies of @agent_forge/forge; do not depend on directly.",
5
5
  "os": [
6
6
  "darwin"