forgex-agent 0.5.8 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +67 -2
  2. package/main.js +12341 -5269
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -44,13 +44,19 @@ forgex
44
44
 
45
45
  | 命令 | 作用 |
46
46
  | --- | --- |
47
- | `/models` | 切换模型;也支持 `/models deepseek-v4-pro` |
47
+ | `/models` | 查看已配置模型、切换任务角色或检查连通性 |
48
+ | `/models role <角色> [model-id]` | 切换 default/cheap/reasoning/coding/vision 角色 |
49
+ | `/models check <model-id>` | 检查凭据并测试模型连通性 |
48
50
  | `/mode [模式]` | 查看/切换权限模式(readonly / standard / trusted / yolo),`Shift+Tab` 循环 |
49
51
  | `/plan` | 进入/退出计划模式:只读分析,不改文件、不执行命令 |
50
52
  | `/connect` | 配置 Provider、API Key、模型,并测试连通性 |
51
53
  | `/key <API Key>` | 保存 API Key(持久化到凭据文件,重开会话仍可用) |
52
54
  | `/context` | 查看当前上下文 token 估算 |
53
55
  | `/session` | 查看当前会话 ID |
56
+ | `/workers`、`/worker <id>` | 查看本地 worker 状态、资源用量和摘要 |
57
+ | `/steer <id> <指令>`、`/cancel-worker <id>` | 指引或取消运行中的 worker |
58
+ | `/retry-worker <id>`、`/wait-worker <id>` | 重试或等待 worker |
59
+ | `/memory ...` | 查看、搜索、修改、导出和审核项目记忆 |
54
60
  | `/help` | 查看帮助 |
55
61
  | `/exit` | 退出(`/quit` 同义) |
56
62
 
@@ -67,6 +73,9 @@ forgex run "检查端口 8080" # 单次任务
67
73
  forgex run --json "..." # JSON 输出
68
74
  forgex run "修复空指针" --worktree # 在独立 Git worktree + 分支中执行,产物可审阅
69
75
  forgex task list|show|diff|clean # 审阅/清理 worktree 任务产物
76
+ forgex workflows # 列出内置工作流
77
+ forgex workflows feature-dev # 查看工作流阶段
78
+ forgex run "实现功能" --workflow feature-dev --requirements
70
79
  forgex sandbox # 查看沙箱能力(区分工作区隔离 / 资源限制 / OS 级隔离)
71
80
  forgex doctor # 环境自检
72
81
  forgex tools # 列出内置工具
@@ -80,6 +89,12 @@ forgex config # 查看最终生效配置(Key 脱敏)
80
89
  门禁命令,不能当作验证通过。
81
90
  `--worktree` 只隔离工作区与改动(独立 worktree + 分支,产物用 `forgex task diff` 审阅),
82
91
  仓库有未提交改动时会直接拒绝,不会 stash/reset。
92
+ `delegate_task` 只在实际会话运行时注册;静态 `forgex tools` 清单不会列出没有执行器的动态工具。会话式 Agent 可一次提交多个独立任务,每个子 Agent 从派发时的 Git 快照创建单独 worktree,完成后返回状态、改动路径和 patch 预览;patch 完整文件默认保存在 `.forgex/subagents/`(与事件日志同目录),不会自动合并回父工作区。父工作区可以有未提交和未跟踪改动,所有 worker 共用同一派发基线。文件工具的读写根限制为 worker 自己的 worktree;命令仍走当前执行策略与审批,worktree 不会限制进程访问外部文件或网络。
93
+
94
+ 父 Agent 对 `delegate_task` 的审批通过后,worker 使用内部 `yolo` 权限模式,不再逐项弹出写入/命令审批。CommandGuard/PolicyEngine 硬拒绝规则以及文件工具的保护路径和 WorkspaceGuard 检查仍然生效;命令进程仍可能访问 worker 目录之外的文件或网络,请只委派可信任务。
95
+
96
+ 子 Agent 并发通过 `agent.subagentMaxConcurrency` 配置,默认 `3`,可设为 `0` 表示不设并发上限;最大配置值为 `32`。子 Agent 不会继续派生子 Agent。包含 Git 子模块或配置了外部 Git clean/smudge/process filter 的仓库会拒绝派发,避免生成不完整快照或运行仓库配置的外部程序。Git worktree 只隔离工作目录,不是 OS 沙箱,也不限制进程访问工作区以外的文件或网络。
97
+ `forgex workflows [<id>]` 可查看内置工作流。`run --workflow <id>` 会把所选工作流阶段作为任务规划提示;任务仍由现有计划执行器和质量门禁负责。`run --requirements` 根据计划生成需求分析与验收标准草案,并将追踪记录写入事件日志;模型生成的验收标准全部标记为未批准,不会伪装成用户确认,也不会阻止当前任务执行。
83
98
 
84
99
  ## 配置
85
100
 
@@ -97,7 +112,57 @@ forgex config # 查看最终生效配置(Key 脱敏)
97
112
  }
98
113
  ```
99
114
 
100
- 支持任意 OpenAI-compatible 接口;Provider 预设见 `forgex connect`。
115
+ 支持 OpenAI-compatible Chat Completions 接口;目前不会将兼容端点冒充为原生 Provider。Provider 预设见 `forgex connect`。多个模型可在 `models` 中配置,并通过 `modelRoles` 为不同任务指定模型:
116
+
117
+ ```json
118
+ {
119
+ "models": [
120
+ {
121
+ "id": "main",
122
+ "baseUrl": "https://api.example.com/v1",
123
+ "apiKeyEnv": "FORGEX_API_KEY",
124
+ "model": "coding-model",
125
+ "contextWindow": 128000,
126
+ "maxOutputTokens": 8192,
127
+ "capabilities": ["chat", "coding", "reasoning"],
128
+ "costTier": 3,
129
+ "speedTier": 3
130
+ }
131
+ ],
132
+ "modelRoles": {
133
+ "default": "main",
134
+ "coding": "main",
135
+ "reasoning": "main"
136
+ }
137
+ }
138
+ ```
139
+
140
+ 旧式 `model` 配置仍然可用。`/models check <model-id>` 可在实际任务前检查连通性;凭据只从指定环境变量或现有凭据文件读取。
141
+
142
+ ### Worker Hub 与 Advisor
143
+
144
+ 父 Agent 可将独立任务派发给本地 worker。每个 worker 在隔离 Git worktree 中运行,Hub 提供状态、进度、用量、摘要和 transcript 查看,以及 steer/cancel/retry/wait 控制;产物需要审阅,不会自动合并。Hub 仅管理本地父子 Agent,不提供远程实时共享会话。
145
+
146
+ Advisor 默认关闭。启用后可按轮检查计划、工具调用、工具结果和最终答复,输出提醒或阻塞意见;Advisor 失败或超时不会阻塞主 Agent。可用 `advisor.modelId` 指定已配置模型,否则使用 reasoning 角色或默认模型。
147
+
148
+ ### 项目记忆
149
+
150
+ 项目记忆默认开启,按工作区隔离,默认写入启动目录下的 `.forgex/memory.jsonl`。设置 `memory.enabled` 为 `false` 可完全关闭记忆读写;`autoRecall` 可单独关闭召回,`autoSave` 默认关闭。以 `记住:...` 或 `remember: ...` 开头的明确陈述会生成待审核候选,不会直接成为长期记忆。审核命令:
151
+
152
+ ```text
153
+ /memory candidates
154
+ /memory approve <candidate-id>
155
+ /memory reject <candidate-id>
156
+ ```
157
+
158
+ `/memory list|search|show|edit|forget|export` 用于管理当前工作区的记忆;`/memory clear confirm` 软删除当前工作区活动记忆并保留历史。修正会创建新版本并标记旧版本为 superseded。敏感内容会被过滤,写入会保留来源和证据引用。
159
+
160
+ ### 编码与外部工具
161
+
162
+ - LSP 支持诊断、符号、定义、引用、hover、code actions 和 rename;WorkspaceEdit 先显示逐文件 diff,再由独立写入工具申请审批后应用。
163
+ - 可配置持久 Python/JavaScript 会话和 DAP adapter;每次执行/调试操作需审批,输出限长。它们以 ForgeX 当前 OS 用户权限运行,不是 OS 沙箱。
164
+ - `web_search` 使用 DuckDuckGo,`github_query` 只读查询 GitHub API。浏览器自动化默认关闭;启用时要求配置浏览器和精确主机 allowlist,使用无凭据临时 profile,每次操作都需审批。
165
+ - 高风险工具的完整审批预览必须可核对;预览过长或需要脱敏时会拒绝操作。
101
166
 
102
167
  ## 安全说明
103
168