ForgeCode：AI增强的终端开发环境与ZSH插件集成

TextMatrix 收录于技术笔记

2026-04-08 约 4756 字预计阅读 12 分钟

ForgeCode：AI增强的终端开发环境与ZSH插件集成

1. 学习目标

通过本文你将掌握：

理解 ForgeCode 的核心价值和设计理念
熟练使用三种模式（交互式/单次CLI/ZSH插件）
掌握三大内置 Agent 的使用场景
理解 ForgeCode 的技术架构
定制和扩展 Agent 行为
最佳实践和常见问题解决

2. 项目概述

2.1 什么是 ForgeCode

"⚒️ Forge: AI-Enhanced Terminal Development Environment"

ForgeCode 是一个全面的 AI 编码助手，将 AI 能力与开发环境深度集成：

核心特性：

特性	说明
零配置	只需添加 API Key 即可使用
无缝集成	直接在终端工作
多提供商	OpenAI/Anthropic/Groq/DeepSeek/Gemini 等 300+ 模型
安全设计	受限 Shell 模式限制文件系统访问
开源透明	Apache-2.0 许可证

安装命令：

curl -fsSL https://forgecode.dev/cli | sh

2.2 项目数据

指标	数值
Stars	6.3k
Forks	1.3k
提交数	2,446
最新版本	v2.8.0 (2026-04-07)
许可证	Apache-2.0

2.3 技术栈

├── Rust 93.5%      — 核心逻辑
├── Shell 3.9%     — 安装脚本
├── HTML 1.2%      — 文档
├── TypeScript 0.9% — 配置
└── 其他 0.5%

3. 三种使用模式

ForgeCode 有三种截然不同的使用方式，理解这个区别可以节省大量时间：

3.1 交互式模式（TUI）

运行 forge 启动持久会话，AI 在对话循环中响应：

forge                           # 启动新会话
forge conversation resume <id>   # 恢复指定会话
forge -C /path/to/project      # 在特定目录启动
forge --sandbox experiment     # 创建隔离的 git worktree

会话中：

输入提示词 → AI 读取文件、写补丁、运行命令
上下文在整会话中保持

3.2 单次 CLI 模式

使用 -p/--prompt 运行单次提示词并退出：

forge -p "Explain src/main.rs"
forge -p "Add error handling to parse()"
echo "What does this do?" | forge
forge commit                    # AI 生成提交信息并提交
forge commit --preview          # 仅生成信息，不提交
forge suggest "find large logs" # 自然语言转 Shell 命令

3.3 ZSH 插件模式（最高效日常开发）

安装插件后，使用 : 前缀命令：

forge setup  # 安装 ZSH 插件

# 日常开发命令
: refactor the auth module
:commit                    # AI 提交
:suggest "find large logs" # 转 Shell 命令
:conversation              # 浏览会话

原理：以 : 开头的命令被拦截并路由到 Forge，其余正常执行。

4. 三大内置 Agent

ForgeCode 内置三个 Agent，各有分工：

Agent	别名	职责	修改文件？
forge	默认	构建功能、修复 Bug、运行测试	✅
sage	:ask	研究：架构映射、数据流追踪、代码阅读	❌
muse	:plan	规划：分析结构、编写计划到 plans/	❌

4.1 切换 Agent

:sage how does caching work?     # 使用 sage 研究
:muse design deployment strategy # 使用 muse 规划
:ask explain this code           # :ask = :sage 别名
:plan create migration plan      # :plan = :muse 别名

# 仅切换 Agent（后续命令使用）
:sage  # 切换到 sage，后续 : <prompt> 都用 sage

4.2 文件附加

使用 @ 附加文件作为上下文：

: review @[src/auth.rs] @[tests/auth_test.rs]

按 Tab 模糊搜索并选择文件。

5. 核心命令详解

5.1 会话管理

:new                        # 新建会话（保存当前）
:new <initial prompt>      # 新建并立即发送提示
:conversation              # fzf 浏览切换会话
:conversation <id>        # 直接切换到指定 ID
:conversation -            # 切换到上一个会话
:clone                     # 分支当前会话（尝试不同方向）
:clone <id>                # 分支指定会话
:rename <name>             # 重命名当前会话
:retry                     # 重试上一个提示
:copy                      # 复制上一个 AI 响应到剪贴板
:dump                       # 导出会话为 JSON
:dump html                 # 导出为 HTML
:compact                   # 手动压缩上下文

5.2 Git 集成

:commit                    # AI 读取 diff，生成提交信息，立即提交
:commit <context>         # 带额外上下文
:commit-preview            # 生成信息到缓冲区，可审阅后手动提交

5.3 Shell 命令工具

:suggest <description>    # 自然语言转 Shell 命令到缓冲区
:edit                     # 在 $EDITOR 中编写多行提示词

5.4 配置命令

# 会话级（关闭终端后重置）
:model <model-id>         # 切换模型
:reasoning-effort <level> # 推理努力：none/minimal/low/medium/high/xhigh/max

# 持久化（保存到配置文件）
:config-model <model-id>  # 设置默认模型 (:cm)
:config-provider          # 设置默认提供商 (:p)
:config-commit-model <id>  # 设置 commit 用模型 (:ccm)
:config-suggest-model <id>  # 设置 suggest 用模型 (:csm)
:config-reload            # 重置会话覆盖到全局配置 (:cr)

# 查看配置
:info                     # 显示当前会话信息
:config                  # 显示有效配置 TOML
:config-edit              # 在 $EDITOR 中编辑配置 (:ce)

6. Skills 系统

Skills 是 AI 可调用的可重用工作流。Forge 内置三个 Skill：

Skill	说明
create-skill	脚手架新自定义 Skill
execute-plan	执行 plans/ 中的计划文件
github-pr-description	从 diff 生成 PR 描述

6.1 自定义 Skills

Skills 路径优先级（高到低）：

位置	路径	范围
项目本地	`.forge/skills/<name>/SKILL.md`	仅当前项目
全局	`~/forge/skills/<name>/SKILL.md`	所有项目
内置	二进制内置	始终可用

6.2 创建新 Skill

: create a new skill

7. 语义搜索（工作区索引）

:sync                      # 索引代码库进行语义搜索
:workspace-init           # 初始化索引
:workspace-status        # 显示索引状态
:workspace-info          # 显示工作区详情

索引后，AI 可以按语义搜索代码而非精确文本匹配。

8. 多 AI 提供商架构

8.1 支持的提供商

OpenAI (GPT-4/GPT-3.5)
Anthropic (Claude 3/2)
Groq
DeepSeek
Gemini
O Series
300+ 模型

8.2 配置提供商

forge provider login     # 交互式配置
forge provider logout    # 移除凭证
forge list provider      # 列出支持的提供商

9. 自定义 Agent 行为

9.1 AGENTS.md

在项目根目录创建 AGENTS.md（或 ~/forge/AGENTS.md 全局）：

---
name: my-agent
model: claude-sonnet-4
---

你的项目编码规范、提交风格、避免事项等持久指令。

9.2 自定义 Agent

在 .forge/agents/（项目）或 ~/forge/agents/（全局）放置 .md 文件：

---
name: reviewer
model: gpt-4
tools: [read, grep, diff]
---

Code review agent instructions...

10. 技术架构

10.1 项目结构

forgecode/
├── crates/
│   └── forge_repo/     # Agent 定义
├── commands/            # 命令定义
├── .forge/
│   ├── agents/         # 自定义 Agent
│   ├── commands/       # 自定义命令
│   └── skills/         # 自定义 Skills
├── templates/           # 模板
├── scripts/            # 脚本
├── docs/               # 文档
├── benchmarks/         # 性能测试
└── shell-plugin/      # ZSH 插件

10.2 核心设计

Restricted Shell 模式：限制文件系统访问，防止意外修改。

对话持久化：所有会话自动保存，可随时恢复。

上下文压缩：:compact 手动压缩上下文释放 Token 预算。

11. 安装与配置

11.1 安装

# YOLO
curl -fsSL https://forgecode.dev/cli | sh

# Nix
nix run github:antinomyhq/forge

11.2 配置 AI 提供商

# 交互式配置
forge provider login

# 设置默认模型
:config-model claude-3-sonnet-4

11.3 ZSH 插件安装

forge setup

12. 与 Claude Code 对比

特性	ForgeCode	Claude Code
语言	Rust	TypeScript
ZSH 插件	✅ 原生支持	❌
多 Agent	✅ forge/sage/muse	❌
Shell 命令转换	✅ suggest	❌
Git 集成	✅ :commit	✅
会话管理	fzf 浏览器	内置
自定义 Skills	✅	❌
工作区索引	✅ :sync	❌

13. 最佳实践

13.1 日常开发工作流

# 早晨：查看任务
:conversation           # 切换到昨天的会话

# 编码中
: refactor the auth middleware
:commit                # 提交

# 遇到问题
:sage trace the data flow in this module

# 写新功能
:muse design the API structure
: implement the endpoints

13.2 安全实践

使用受限 Shell 模式
定期 :compact 压缩上下文
不在公开频道分享会话 ID

13.3 性能优化

# 上下文快满了
:compact

# 查看 Token 使用
:conversation stats <id>

# 使用轻量模型处理简单任务
:config-model gpt-3.5-turbo

14. 常见问题

Q: 如何切换模型？

:config-model claude-3-opus-4  # 持久化
:model gpt-4  # 仅当前会话

Q: :conversation resume 无响应？

它会打开交互式 TUI，输入提示词或按 Ctrl+C 退出。

Q: 如何自托管工作区服务器？

export FORGE_WORKSPACE_SERVER_URL=http://localhost:8080
:sync

Q: 支持哪些 IDE？

终端集成，任何 IDE 配合终端使用。

15. 总结

ForgeCode 是 AI 编码助手的终端原生方案：

特性	说明
Rust 高性能	93.5% Rust 实现
三模式	交互/CLI/ZSH 插件
多 Agent	forge/sage/muse 分工
多提供商	300+ 模型支持
开源免费	Apache-2.0

适用场景：

终端重度用户
需要 ZSH 集成的工作流
多 Agent 协作开发
习惯 CLI 的开发者

🦞 每日08:00自动更新