[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-antinomyhq--forgecode":3,"tool-antinomyhq--forgecode":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",157379,2,"2026-04-15T23:32:42",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":77,"owner_twitter":73,"owner_website":78,"owner_url":79,"languages":80,"stars":108,"forks":109,"last_commit_at":110,"license":111,"difficulty_score":32,"env_os":112,"env_gpu":113,"env_ram":113,"env_deps":114,"category_tags":120,"github_topics":121,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":138,"updated_at":139,"faqs":140,"releases":171},7868,"antinomyhq\u002Fforgecode","forgecode","AI enabled pair programmer for Claude, GPT, O Series, Grok, Deepseek, Gemini and 300+ models","Forge 是一款专为开发者打造的 AI 增强型终端编程助手，旨在将大语言模型的智能深度融入日常开发工作流。它支持 Claude、GPT、Grok、Deepseek、Gemini 等超过 300 种主流 AI 模型，让开发者能够灵活选择最适合自己的智力伙伴。\n\n在传统开发中，切换上下文去网页端与 AI 对话往往打断思路，而 Forge 直接运行在终端内，让你无需离开代码环境即可享受“结对编程”体验。它能帮你快速理解复杂的项目架构、规划新功能实现路径，甚至协助定位和修复 Bug。无论是梳理认证系统的逻辑流转，还是为 React 应用搭建深色模式组件，Forge 都能基于当前代码库提供精准建议并生成相应代码。\n\nForge 的独特之处在于其灵活的交互模式：既提供沉浸式的文本用户界面（TUI）进行多轮对话，也支持通过 ZSH 插件以冒号前缀（如`:explain`）快速调用特定技能，还能作为一次性命令直接执行。此外，它还具备语义搜索、Git 集成及多智能体协作能力，能像资深同事一样理解你的项目语境。\n\n这款工具非常适合希望提升编码效率的软件工程师、全栈开发者及技术研究人员。如果你习惯在命令行","Forge 是一款专为开发者打造的 AI 增强型终端编程助手，旨在将大语言模型的智能深度融入日常开发工作流。它支持 Claude、GPT、Grok、Deepseek、Gemini 等超过 300 种主流 AI 模型，让开发者能够灵活选择最适合自己的智力伙伴。\n\n在传统开发中，切换上下文去网页端与 AI 对话往往打断思路，而 Forge 直接运行在终端内，让你无需离开代码环境即可享受“结对编程”体验。它能帮你快速理解复杂的项目架构、规划新功能实现路径，甚至协助定位和修复 Bug。无论是梳理认证系统的逻辑流转，还是为 React 应用搭建深色模式组件，Forge 都能基于当前代码库提供精准建议并生成相应代码。\n\nForge 的独特之处在于其灵活的交互模式：既提供沉浸式的文本用户界面（TUI）进行多轮对话，也支持通过 ZSH 插件以冒号前缀（如`:explain`）快速调用特定技能，还能作为一次性命令直接执行。此外，它还具备语义搜索、Git 集成及多智能体协作能力，能像资深同事一样理解你的项目语境。\n\n这款工具非常适合希望提升编码效率的软件工程师、全栈开发者及技术研究人员。如果你习惯在命令行工作，并希望让 AI 成为触手可及的实时搭档，Forge 将极大优化你的开发体验。","\u003Ch1 align=\"center\">⚒️ Forge: AI-Enhanced Terminal Development Environment\u003C\u002Fh1>\n\u003Cp align=\"center\">A comprehensive coding agent that integrates AI capabilities with your development environment\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Ccode>curl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\u003C\u002Fcode>\u003C\u002Fp>\n\n[![CI Status](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Ftailcallhq\u002Fforgecode\u002Fci.yml?style=for-the-badge)](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Factions)\n[![GitHub Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Ftailcallhq\u002Fforgecode?style=for-the-badge)](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Freleases)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https:\u002F\u002Fdiscord.gg\u002FkRZBPpkgwq)\n[![CLA assistant](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fantinomyhq_forgecode_readme_5000b64aa31f.png)](https:\u002F\u002Fcla-assistant.io\u002Ftailcallhq\u002Fforgecode)\n\n![Code-Forge Demo](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fantinomyhq_forgecode_readme_cb5d35c670ff.gif)\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Table of Contents\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- [Quickstart](#quickstart)\n- [Usage Examples](#usage-examples)\n- [Why Forge?](#why-forge)\n- [How Forge Works: Three Modes](#how-forge-works-three-modes)\n  - [Interactive Mode (TUI)](#interactive-mode-tui)\n  - [One-Shot CLI Mode](#one-shot-cli-mode)\n  - [ZSH Plugin Mode (`:` prefix)](#zsh-plugin-mode--prefix)\n- [ZSH Plugin: The `:` Prefix System](#zsh-plugin-the--prefix-system)\n  - [Agents](#agents)\n  - [Sending Prompts](#sending-prompts)\n  - [Attaching Files](#attaching-files)\n  - [Conversation Management](#conversation-management)\n  - [Git Integration](#git-integration)\n  - [Shell Command Tools](#shell-command-tools)\n  - [Session & Configuration](#session--configuration)\n  - [Skills](#skills)\n  - [Customizing Agent Behavior](#customizing-agent-behavior)\n  - [Semantic Search (Workspace)](#semantic-search-workspace)\n  - [Quick Reference: All `:` Commands](#quick-reference-all--commands)\n- [Command-Line Options](#command-line-options)\n- [Advanced Configuration](#advanced-configuration)\n  - [Provider Configuration](#provider-configuration)\n    - [Managing Provider Credentials](#managing-provider-credentials)\n    - [Deprecated: Environment Variables](#deprecated-environment-variables)\n  - [forge.yaml Configuration Options](#forgeyaml-configuration-options)\n  - [Environment Variables](#environment-variables)\n  - [MCP Configuration](#mcp-configuration)\n  - [Example Use Cases](#example-use-cases)\n  - [Usage in Multi-Agent Workflows](#usage-in-multi-agent-workflows)\n- [Documentation](#documentation)\n- [Community](#community)\n- [Support Us](#support-us)\n\n\u003C\u002Fdetails>\n\n---\n\n## Quickstart\n\nTo get started with Forge, run the command below:\n\n```bash\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n```\n\nOn first run, Forge will guide you through setting up your AI provider credentials using the interactive login flow. Alternatively, you can configure providers beforehand:\n\n```bash\n# Configure your provider credentials interactively\nforge provider login\n\n# Then start Forge\nforge\n```\nThat's it! Forge is now ready to assist you with your development tasks.\n\n## Usage Examples\n\nForge can be used in different ways depending on your needs. Here are some common usage patterns:\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Code Understanding\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> Can you explain how the authentication system works in this codebase?\n```\n\nForge will analyze your project's structure, identify authentication-related files, and provide a detailed explanation of the authentication flow, including the relationships between different components.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Implementing New Features\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I need to add a dark mode toggle to our React application. How should I approach this?\n```\n\nForge will suggest the best approach based on your current codebase, explain the steps needed, and even scaffold the necessary components and styles for you.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Debugging Assistance\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I'm getting this error: \"TypeError: Cannot read property 'map' of undefined\". What might be causing it?\n```\n\nForge will analyze the error, suggest potential causes based on your code, and propose different solutions to fix the issue.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Code Reviews\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> Please review the code in src\u002Fcomponents\u002FUserProfile.js and suggest improvements\n```\n\nForge will analyze the code, identify potential issues, and suggest improvements for readability, performance, security, and maintainability.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Learning New Technologies\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I want to integrate GraphQL into this Express application. Can you explain how to get started?\n```\n\nForge will provide a tailored tutorial on integrating GraphQL with Express, using your specific project structure as context.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Database Schema Design\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I need to design a database schema for a blog with users, posts, comments, and categories\n```\n\nForge will suggest an appropriate schema design, including tables\u002Fcollections, relationships, indexes, and constraints based on your project's existing database technology.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Refactoring Legacy Code\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> Help me refactor this class-based component to use React Hooks\n```\n\nForge can help modernize your codebase by walking you through refactoring steps and implementing them with your approval.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Git Operations\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> I need to merge branch 'feature\u002Fuser-profile' into main but there are conflicts\n```\n\nForge can guide you through resolving git conflicts, explaining the differences and suggesting the best way to reconcile them.\n\n\u003C\u002Fdetails>\n\n## Why Forge?\n\nForge is designed for developers who want to enhance their workflow with AI assistance while maintaining full control over their development environment.\n\n- **Zero configuration** - Just add your API key and you're ready to go\n- **Seamless integration** - Works right in your terminal, where you already work\n- **Multi-provider support** - Use OpenAI, Anthropic, or other LLM providers\n- **Secure by design** - Restricted shell mode limits file system access and prevents unintended changes\n- **Open-source** - Transparent, extensible, and community-driven\n\nForge helps you code faster, solve complex problems, and learn new technologies without leaving your terminal.\n\n---\n\n## How Forge Works: Three Modes\n\nForge has three distinct ways to use it. Understanding this distinction upfront will save you confusion.\n\n### Interactive Mode (TUI)\n\nRunning `forge` with no arguments starts the interactive terminal UI, a persistent session where you type prompts and the AI responds in a conversational loop. This is the primary way to do multi-step work.\n\n```bash\nforge                              # Start a new interactive session\nforge conversation resume \u003Cid>     # Resume a specific saved conversation in interactive mode\nforge --conversation-id \u003Cid>       # Same: resume conversation by ID\nforge --agent \u003Cagent-id>           # Start interactive session with a specific agent\nforge -C \u002Fpath\u002Fto\u002Fproject          # Start in a specific directory\nforge --sandbox experiment-name    # Create an isolated git worktree + branch, then start there\n```\n\nOnce inside interactive mode, type your prompt and press Enter. Forge reads files, writes patches, runs commands, and maintains context across the whole session.\n\n### One-Shot CLI Mode\n\nPass `-p` (or `--prompt`) to run a single prompt and exit. Forge does the work and returns to your shell. Useful for scripts, piping output, or quick tasks.\n\n```bash\nforge -p \"Explain the purpose of src\u002Fmain.rs\"\nforge -p \"Add error handling to the parse() function in lib.rs\"\necho \"What does this do?\" | forge    # Pipe input as the prompt\nforge commit                         # Generate an AI commit message and commit (exits when done)\nforge commit --preview               # Generate commit message, print it, then exit\nforge suggest \"find large log files\" # Translate natural language to a shell command, then exit\n```\n\n> **Note:** `forge conversation resume \u003Cid>` opens the interactive TUI. It does **not** just print a message and exit. If you run it and see the cursor waiting, you are inside the interactive session. Type your prompt or press `Ctrl+C` to exit.\n\n### ZSH Plugin Mode (`:` prefix)\n\nInstall the ZSH plugin once with `forge setup`, then use `:` commands directly at your shell prompt without ever typing `forge`. This is the fastest mode for day-to-day development: send prompts, switch conversations, commit, and suggest commands without leaving your shell.\n\n```zsh\n: refactor the auth module      # Send a prompt to the active agent\n:commit                         # AI-powered git commit\n:suggest \"find large log files\" # Translate description → shell command in your buffer\n:conversation                   # Browse saved conversations with fzf preview\n```\n\nSee the full [ZSH Plugin reference below](#zsh-plugin-the--prefix-system) for all commands and aliases.\n\n---\n\n## ZSH Plugin: The `:` Prefix System\n\nWhen you install the ZSH plugin (`forge setup`), you get a `:` prefix command system at your shell prompt. This is the fastest way to use Forge during normal development; you never leave your shell.\n\n**How it works:** Lines starting with `:` are intercepted before the shell sees them and routed to Forge. Everything else runs normally.\n\n```zsh\n: \u003Cprompt>         # Send a prompt to the active agent\n:sage \u003Cprompt>     # Send a prompt to a specific agent by name (sage, muse, forge, or any custom agent)\n:agent \u003Cname>      # Switch the active agent; opens fzf picker if no name given\n```\n\n### Agents\n\nForge ships with three built-in agents, each with a different role:\n\n| Agent | Alias | Purpose | Modifies files? |\n|---|---|---|---|\n| `forge` | (default) | Implementation: builds features, fixes bugs, and runs tests | Yes |\n| `sage` | `:ask` | Research: maps architecture, traces data flow, and reads code | No |\n| `muse` | `:plan` | Planning: analyzes structure and writes implementation plans to `plans\u002F` | No |\n\n### Sending Prompts\n\n```zsh\n: refactor the auth module to use the new middleware\n:sage how does the caching layer work?    # sage = read-only research agent\n:muse design a deployment strategy        # muse = planning agent (writes to plans\u002F)\n:ask how does X work?                     # alias for :sage\n:plan create a migration plan             # alias for :muse\n```\n\nThe agent context persists. Typing `:sage` alone (no prompt text) switches the active agent to sage for all subsequent `: \u003Cprompt>` commands.\n\n### Attaching Files\n\nType `@` in a prompt, then press Tab to fuzzy-search and select files. The path is inserted as `@[filename]` and attached as context to the AI.\n\n```zsh\n: review this code @[src\u002Fauth.rs] @[tests\u002Fauth_test.rs]\n```\n\n### Conversation Management\n\nForge saves every conversation. You can switch between them like switching directories.\n\n```zsh\n:new                      # Start a fresh conversation (saves current for :conversation -)\n:new \u003Cinitial prompt>     # Start a new conversation and immediately send a prompt\n:conversation             # Open fzf picker: browse and switch conversations with preview\n:conversation \u003Cid>        # Switch directly to a conversation by ID\n:conversation -           # Toggle between current and previous conversation (like cd -)\n:clone                    # Branch the current conversation (try a different direction)\n:clone \u003Cid>               # Clone a specific conversation by ID\n:rename \u003Cname>            # Rename the current conversation\n:conversation-rename      # Rename a conversation via fzf picker\n:retry                    # Retry the last prompt (useful if the AI misunderstood)\n:copy                     # Copy the last AI response to clipboard as markdown\n:dump                     # Export conversation as JSON\n:dump html                # Export conversation as formatted HTML\n:compact                  # Manually compact context to free up token budget\n```\n\n### Git Integration\n\n```zsh\n:commit                   # AI reads your diff, writes a commit message, and commits immediately\n:commit \u003Ccontext>         # Same, but pass extra context: :commit fix typo in readme\n:commit-preview           # AI generates the message and puts \"git commit -m '...'\" in your buffer\n                          # so you can review\u002Fedit the message before pressing Enter\n```\n\n### Shell Command Tools\n\n```zsh\n:suggest \u003Cdescription>    # Translate natural language to a shell command and put it in your buffer\n:edit                     # Open $EDITOR to compose a complex multi-line prompt, then send it\n```\n\n### Session & Configuration\n\nSome commands change settings for the current session only. Others persist to your config file (`~\u002Fforge\u002F.forge.toml`). The distinction matters:\n\n```zsh\n# Session-only (reset when you close the terminal; not saved to config)\n:model \u003Cmodel-id>              # Change model for this session only\n:reasoning-effort \u003Clevel>      # Set reasoning effort: none\u002Fminimal\u002Flow\u002Fmedium\u002Fhigh\u002Fxhigh\u002Fmax\n:agent \u003Cid>                    # Switch active agent for this session\n\n# Persistent (saved to config file)\n:config-model \u003Cmodel-id>       # Set default model globally  (alias: :cm)\n:config-provider               # Switch provider globally    (alias: :provider, :p)\n:config-reasoning-effort \u003Clvl> # Set default reasoning effort globally (alias: :cre)\n:config-commit-model \u003Cid>      # Set model used for :commit  (alias: :ccm)\n:config-suggest-model \u003Cid>     # Set model used for :suggest (alias: :csm)\n:config-reload                 # Reset session overrides back to global config (alias: :cr)\n\n# View & edit config\n:info                          # Show current session info (model, agent, conversation ID)\n:config                        # Display effective resolved configuration in TOML format\n:config-edit                   # Open config file in $EDITOR (alias: :ce)\n:tools                         # List available tools for the current agent\n:skill                         # List available skills\n```\n\n### Skills\n\nSkills are reusable workflows the AI can invoke as tools. Forge ships three built-in skills:\n\n- **`create-skill`**: scaffold a new custom skill\n- **`execute-plan`**: execute a plan file from `plans\u002F`\n- **`github-pr-description`**: generate a PR description from your diff\n\nUse `:skill` to list available skills. The AI invokes them automatically when relevant, or you can ask explicitly: `: generate a PR description using the github-pr-description skill`.\n\n**Custom skills** live in `SKILL.md` files with YAML front-matter. Precedence (highest first):\n\n| Location | Path | Scope |\n|---|---|---|\n| Project-local | `.forge\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | This project only |\n| Global | `~\u002Fforge\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | All projects |\n| Built-in | Embedded in binary | Always available |\n\nProject-local skills override global ones, which override built-in ones. To scaffold a new skill, ask: `: create a new skill`.\n\n### Customizing Agent Behavior\n\n**`AGENTS.md`:** Create this file in your project root (or `~\u002Fforge\u002FAGENTS.md` globally) to give all agents persistent instructions such as coding conventions, commit message style, and things to avoid. Forge reads it automatically at the start of every conversation.\n\n**Custom agents:** Place a `.md` file with YAML front-matter in `.forge\u002Fagents\u002F` (project) or `~\u002Fforge\u002Fagents\u002F` (global) to define additional agents with their own models, tools, and system prompts. Project-local agents override global ones. The built-in agent files in `crates\u002Fforge_repo\u002Fsrc\u002Fagents\u002F` are good examples of the format.\n\n**Custom commands:** Place YAML files in `.forge\u002Fcommands\u002F` (project) or `~\u002Fforge\u002Fcommands\u002F` (global) to define shortcut commands available via `:commandname`. Commands can also be defined inline in `forge.yaml` under the `commands:` key.\n\n### Semantic Search (Workspace)\n\n```zsh\n:sync                     # Index your codebase for semantic search\n:workspace-init           # Initialize workspace for indexing\n:workspace-status         # Show indexing status\n:workspace-info           # Show workspace details\n```\n\nAfter running `:sync`, the AI can search your codebase by meaning rather than exact text matches. Indexing sends file content to the workspace server, which defaults to `https:\u002F\u002Fapi.forgecode.dev`. Set `FORGE_WORKSPACE_SERVER_URL` to override this if self-hosting.\n\n### Quick Reference: All `:` Commands\n\n\n| Command | Alias | What it does |\n|---|---|---|\n| `: \u003Cprompt>` | | Send prompt to active agent |\n| `:new` | `:n` | Start new conversation |\n| `:conversation` | `:c` | Browse\u002Fswitch conversations (fzf) |\n| `:conversation -` | | Toggle to previous conversation |\n| `:clone` | | Branch current conversation |\n| `:rename \u003Cname>` | `:rn` | Rename current conversation |\n| `:conversation-rename` | | Rename conversation (fzf picker) |\n| `:retry` | `:r` | Retry last prompt |\n| `:copy` | | Copy last response to clipboard |\n| `:dump` | `:d` | Export conversation as JSON |\n| `:compact` | | Compact context |\n| `:commit` | | AI commit (immediate) |\n| `:commit-preview` | | AI commit (review first) |\n| `:suggest \u003Cdesc>` | `:s` | Translate natural language to command |\n| `:edit` | `:ed` | Compose prompt in $EDITOR |\n| `:sage \u003Cprompt>` | `:ask` | Q&A \u002F code understanding agent |\n| `:muse \u003Cprompt>` | `:plan` | Planning agent |\n| `:agent \u003Cname>` | `:a` | Switch active agent (fzf picker if no name given) |\n| `:model \u003Cid>` | `:m` | Set model for this session only |\n| `:config-model \u003Cid>` | `:cm` | Set default model (persistent) |\n| `:reasoning-effort \u003Clvl>` | `:re` | Set reasoning effort for session |\n| `:config-reload` | `:cr` | Reset session overrides to global config |\n| `:info` | `:i` | Show session info |\n| `:sync` | `:workspace-sync` | Index codebase for semantic search |\n| `:tools` | `:t` | List available tools |\n| `:skill` | | List available skills |\n| `:login` | `:provider-login` | Login to a provider |\n| `:logout` | | Logout from a provider |\n| `:keyboard-shortcuts` | `:kb` | Show keyboard shortcuts |\n| `:doctor` | | Run shell environment diagnostics |\n\n---\n\n## Command-Line Options\n\nHere's a quick reference of Forge's command-line options:\n\n| Option                              | Description                                                              |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| `-p, --prompt \u003CPROMPT>`             | Direct prompt to process without entering interactive mode               |\n| `-e, --event \u003CEVENT>`               | Dispatch an event to the workflow in JSON format                         |\n| `--conversation \u003CCONVERSATION>`     | Path to a JSON file containing the conversation to execute               |\n| `--conversation-id \u003CID>`            | Resume or continue an existing conversation by ID                        |\n| `--agent \u003CAGENT>`                   | Agent ID to use for this session                                         |\n| `-C, --directory \u003CDIR>`             | Change to this directory before starting                                 |\n| `--sandbox \u003CNAME>`                  | Create an isolated git worktree + branch for safe experimentation        |\n| `--verbose`                         | Enable verbose logging output                                            |\n| `-h, --help`                        | Print help information                                                   |\n| `-V, --version`                     | Print version                                                            |\n\n### Subcommands\n\n```bash\n# Conversations\nforge conversation list                  # List all saved conversations\nforge conversation resume \u003Cid>           # Resume a conversation in interactive mode\nforge conversation new                   # Create a new conversation ID (prints it)\nforge conversation dump \u003Cid>             # Export conversation as JSON\nforge conversation compact \u003Cid>          # Compact conversation context\nforge conversation retry \u003Cid>            # Retry last message\nforge conversation clone \u003Cid>            # Clone a conversation\nforge conversation rename \u003Cid> \u003Cname>    # Rename a conversation\nforge conversation delete \u003Cid>           # Delete a conversation permanently\nforge conversation info \u003Cid>             # Show conversation details\nforge conversation stats \u003Cid>            # Show token usage statistics\nforge conversation show \u003Cid>             # Show last assistant message\n\n# Commits\nforge commit                             # Generate AI commit message and commit\nforge commit --preview                   # Generate commit message only (prints it)\nforge commit fix the auth bug            # Pass extra context for the commit message\n\n# Shell command suggestion\nforge suggest \"list files by size\"       # Translate description to a shell command\n\n# Providers\nforge provider login                     # Add or update provider credentials (interactive)\nforge provider logout                    # Remove provider credentials\nforge list provider                      # List supported providers\n\n# Models & agents\nforge list model                         # List available models\nforge list agent                         # List available agents\n\n# Workspace \u002F semantic search\nforge workspace sync                     # Index current directory for semantic search\nforge workspace init                     # Initialize workspace\nforge workspace status                   # Show indexing status\nforge workspace query \u003Ctext>             # Query the semantic index\n\n# MCP servers\nforge mcp list                           # List configured MCP servers\nforge mcp import                         # Add a server from JSON\nforge mcp show                           # Show server configuration\nforge mcp remove                         # Remove a server\nforge mcp reload                         # Reload all servers and rebuild caches\n\n# Other\nforge info                               # Show config, active model, environment\nforge list tool --agent \u003Cid>             # List tools for a specific agent\nforge doctor                             # Run shell environment diagnostics\nforge update                             # Update forge to the latest version\nforge setup                              # Install ZSH plugin (updates .zshrc)\n```\n\n## Advanced Configuration\n\n### Provider Configuration\n\nForge supports multiple AI providers. The recommended way to configure providers is using the interactive login command:\n\n```bash\nforge provider login\n```\n\nThis will:\n\n1. Show you a list of available providers\n2. Guide you through entering the required credentials\n\n#### Managing Provider Credentials\n\n```bash\n# Login to a provider (add or update credentials)\nforge provider login\n\n# Remove provider credentials\nforge provider logout\n\n# List supported providers\nforge provider list\n```\n\n#### Deprecated: Environment Variables\n\n> **⚠️ DEPRECATED**: Using `.env` files for provider configuration is deprecated and will be removed in a future version. Please use `forge provider login` instead.\n\nFor backward compatibility, Forge still supports environment variables. On first run, any credentials found in environment variables will be automatically migrated to file-based storage.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Legacy Environment Variable Setup (Deprecated)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenRouter\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENROUTER_API_KEY=\u003Cyour_openrouter_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Requesty\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nREQUESTY_API_KEY=\u003Cyour_requesty_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>x-ai\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nXAI_API_KEY=\u003Cyour_xai_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>z.ai\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nZAI_API_KEY=\u003Cyour_zai_api_key>\n\n# Or for coding plan subscription\nZAI_CODING_API_KEY=\u003Cyour_zai_coding_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Cerebras\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nCEREBRAS_API_KEY=\u003Cyour_cerebras_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>IO Intelligence\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nIO_INTELLIGENCE_API_KEY=\u003Cyour_io_intelligence_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: meta-llama\u002FLlama-3.3-70B-Instruct\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenAI\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_openai_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: o3-mini-high\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Anthropic\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nANTHROPIC_API_KEY=\u003Cyour_anthropic_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: claude-3.7-sonnet\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Google Vertex AI\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Setup Instructions:**\n\n1. **Install Google Cloud CLI** and authenticate:\n\n   ```bash\n   gcloud auth login\n   gcloud config set project YOUR_PROJECT_ID\n   ```\n\n2. **Get your authentication token**:\n\n   ```bash\n   gcloud auth print-access-token\n   ```\n\n3. **Use the token when logging in via Forge**:\n\n   ```bash\n   forge provider login\n   # Select Google Vertex AI and enter your credentials\n   ```\n\n**Legacy `.env` setup:**\n\n```bash\n# .env\nPROJECT_ID=\u003Cyour_project_id>\nLOCATION=\u003Cyour_location>\nVERTEX_AI_AUTH_TOKEN=\u003Cyour_auth_token>\n```\n\n```yaml\n# forge.yaml\nmodel: google\u002Fgemini-2.5-pro\n```\n\n**Available Models:**\n- Claude models: `claude-sonnet-4@20250514`\n- Gemini models: `gemini-2.5-pro`, `gemini-2.0-flash`\n\nUse the `\u002Fmodel` command in Forge CLI to see all available models.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenAI-Compatible Providers\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_provider_api_key>\nOPENAI_URL=\u003Cyour_provider_url>\n```\n\n```yaml\n# forge.yaml\nmodel: \u003Cprovider-specific-model>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Groq\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_groq_api_key>\nOPENAI_URL=https:\u002F\u002Fapi.groq.com\u002Fopenai\u002Fv1\n```\n\n```yaml\n# forge.yaml\nmodel: deepseek-r1-distill-llama-70b\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Amazon Bedrock\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nTo use Amazon Bedrock models with Forge, you'll need to first set up the [Bedrock Access Gateway](https:\u002F\u002Fgithub.com\u002Faws-samples\u002Fbedrock-access-gateway):\n\n1. **Set up Bedrock Access Gateway**:\n\n   - Follow the deployment steps in the [Bedrock Access Gateway repo](https:\u002F\u002Fgithub.com\u002Faws-samples\u002Fbedrock-access-gateway)\n   - Create your own API key in Secrets Manager\n   - Deploy the CloudFormation stack\n   - Note your API Base URL from the CloudFormation outputs\n\n2. **Configure in Forge**:\n\n   ```bash\n   forge provider login\n   # Select OpenAI-compatible provider and enter your Bedrock Gateway details\n   ```\n\n**Legacy `.env` setup:**\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_bedrock_gateway_api_key>\nOPENAI_URL=\u003Cyour_bedrock_gateway_base_url>\n```\n\n```yaml\n# forge.yaml\nmodel: anthropic.claude-3-opus\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>ForgeCode Services\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nFORGE_API_KEY=\u003Cyour_forge_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: claude-3.7-sonnet\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n---\n\n### forge.yaml Configuration Options\n\n### Environment Variables\n\nForge supports several environment variables for advanced configuration and fine-tuning. These can be set in your `.env` file or system environment.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Retry Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl how Forge handles retry logic for failed requests:\n\n```bash\n# .env\nFORGE_RETRY_INITIAL_BACKOFF_MS=1000    # Initial backoff time in milliseconds (default: 1000)\nFORGE_RETRY_BACKOFF_FACTOR=2           # Multiplier for backoff time (default: 2)\nFORGE_RETRY_MAX_ATTEMPTS=3             # Maximum retry attempts (default: 3)\nFORGE_SUPPRESS_RETRY_ERRORS=false      # Suppress retry error messages (default: false)\nFORGE_RETRY_STATUS_CODES=429,500,502   # HTTP status codes to retry (default: 429,500,502,503,504)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>HTTP Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nFine-tune HTTP client behavior for API requests:\n\n```bash\n# .env\nFORGE_HTTP_CONNECT_TIMEOUT=30              # Connection timeout in seconds (default: 30)\nFORGE_HTTP_READ_TIMEOUT=900                # Read timeout in seconds (default: 900)\nFORGE_HTTP_POOL_IDLE_TIMEOUT=90            # Pool idle timeout in seconds (default: 90)\nFORGE_HTTP_POOL_MAX_IDLE_PER_HOST=5        # Max idle connections per host (default: 5)\nFORGE_HTTP_MAX_REDIRECTS=10                # Maximum redirects to follow (default: 10)\nFORGE_HTTP_USE_HICKORY=false               # Use Hickory DNS resolver (default: false)\nFORGE_HTTP_TLS_BACKEND=default             # TLS backend: \"default\" or \"rustls\" (default: \"default\")\nFORGE_HTTP_MIN_TLS_VERSION=1.2             # Minimum TLS version: \"1.0\", \"1.1\", \"1.2\", \"1.3\"\nFORGE_HTTP_MAX_TLS_VERSION=1.3             # Maximum TLS version: \"1.0\", \"1.1\", \"1.2\", \"1.3\"\nFORGE_HTTP_ADAPTIVE_WINDOW=true            # Enable HTTP\u002F2 adaptive window (default: true)\nFORGE_HTTP_KEEP_ALIVE_INTERVAL=60          # Keep-alive interval in seconds (default: 60, use \"none\"\u002F\"disabled\" to disable)\nFORGE_HTTP_KEEP_ALIVE_TIMEOUT=10           # Keep-alive timeout in seconds (default: 10)\nFORGE_HTTP_KEEP_ALIVE_WHILE_IDLE=true      # Keep-alive while idle (default: true)\nFORGE_HTTP_ACCEPT_INVALID_CERTS=false      # Accept invalid certificates (default: false) - USE WITH CAUTION\nFORGE_HTTP_ROOT_CERT_PATHS=\u002Fpath\u002Fto\u002Fcert1.pem,\u002Fpath\u002Fto\u002Fcert2.crt  # Paths to root certificate files (PEM, CRT, CER format), multiple paths separated by commas\n```\n\n> **⚠️ Security Warning**: Setting `FORGE_HTTP_ACCEPT_INVALID_CERTS=true` disables SSL\u002FTLS certificate verification, which can expose you to man-in-the-middle attacks. Only use this in development environments or when you fully trust the network and endpoints.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>API Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nOverride default API endpoints and provider\u002Fmodel settings:\n\n```bash\n# .env\nFORGE_API_URL=https:\u002F\u002Fapi.forgecode.dev  # Custom Forge API URL (default: https:\u002F\u002Fapi.forgecode.dev)\nFORGE_WORKSPACE_SERVER_URL=http:\u002F\u002Flocalhost:8080  # URL for the indexing server (default: https:\u002F\u002Fapi.forgecode.dev\u002F)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Tool Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfiguring the tool calls settings:\n\n```bash\n# .env\nFORGE_TOOL_TIMEOUT=300         # Maximum execution time in seconds for a tool before it is terminated to prevent hanging the session. (default: 300)\nFORGE_MAX_IMAGE_SIZE=10485760  # Maximum image file size in bytes for read_image operations (default: 10485760 - 10 MB)\nFORGE_DUMP_AUTO_OPEN=false     # Automatically open dump files in browser (default: false)\nFORGE_DEBUG_REQUESTS=\u002Fpath\u002Fto\u002Fdebug\u002Frequests.json  # Write debug HTTP request files to specified path (supports absolute and relative paths)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>ZSH Plugin Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure the ZSH plugin behavior:\n\n```bash\n# .env\nFORGE_BIN=forge                    # Command to use for forge operations (default: \"forge\")\n```\n\nThe `FORGE_BIN` environment variable allows you to customize the command used by the ZSH plugin when transforming `:` prefixed commands. If not set, it defaults to `\"forge\"`.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Display Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure display options for the Forge UI and ZSH theme:\n\n```bash\n# .env\nFORGE_CURRENCY_SYMBOL=\"$\"         # Currency symbol for cost display in ZSH theme (default: \"$\")\nFORGE_CURRENCY_CONVERSION_RATE=1.0  # Conversion rate for currency display (default: 1.0)\nNERD_FONT=1                       # Enable Nerd Font icons in ZSH theme (default: auto-detected, set to \"1\" or \"true\" to enable, \"0\" or \"false\" to disable)\nUSE_NERD_FONT=1                   # Alternative variable for enabling Nerd Font icons (same behavior as NERD_FONT)\n```\n\nThe `FORGE_CURRENCY_SYMBOL` and `FORGE_CURRENCY_CONVERSION_RATE` variables control how costs are displayed in the ZSH theme right prompt. Use these to customize the currency display for your region or preferred currency.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>System Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nSystem-level environment variables (usually set automatically):\n\n```bash\n# .env\nFORGE_CONFIG=\u002Fcustom\u002Fconfig\u002Fdir        # Base directory for all Forge config files (default: ~\u002F.forge)\nFORGE_MAX_SEARCH_RESULT_BYTES=10240   # Maximum bytes for search results (default: 10240 - 10 KB)\nFORGE_HISTORY_FILE=\u002Fpath\u002Fto\u002Fhistory    # Custom path for Forge history file (default: uses system default location)\nFORGE_BANNER=\"Your custom banner text\" # Custom banner text to display on startup (default: Forge ASCII art)\nFORGE_MAX_CONVERSATIONS=100            # Maximum number of conversations to show in list (default: 100)\nFORGE_MAX_LINE_LENGTH=2000             # Maximum characters per line for file read operations (default: 2000)\nFORGE_STDOUT_MAX_LINE_LENGTH=2000      # Maximum characters per line for shell output (default: 2000)\nSHELL=\u002Fbin\u002Fzsh                         # Shell to use for command execution (Unix\u002FLinux\u002FmacOS)\nCOMSPEC=cmd.exe                        # Command processor to use (Windows)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Semantic Search Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure semantic search behavior for code understanding:\n\n```bash\n# .env\nFORGE_SEM_SEARCH_LIMIT=200            # Maximum number of results to return from initial vector search (default: 200)\nFORGE_SEM_SEARCH_TOP_K=20             # Top-k parameter for relevance filtering during semantic search (default: 20)\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Logging Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nConfigure logging verbosity and output:\n\n```bash\n# .env\nFORGE_LOG=forge=info                  # Log filter level (default: forge=debug when tracking disabled, forge=info when tracking enabled)\n```\n\nThe `FORGE_LOG` variable controls the logging level for Forge's internal operations using the standard tracing filter syntax. Common values:\n- `forge=error` - Only errors\n- `forge=warn` - Warnings and errors\n- `forge=info` - Informational messages (default when tracking enabled)\n- `forge=debug` - Debug information (default when tracking disabled)\n- `forge=trace` - Detailed tracing\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Tracking Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl tracking of user-identifying metadata in telemetry events:\n\n```bash\n# .env\nFORGE_TRACKER=false                   # Disable tracking enrichment metadata (default: true)\n```\n\nThe `FORGE_TRACKER` variable controls whether tracking enrichment metadata is included in telemetry events.\n\n\u003C\u002Fdetails>\n\nThe `forge.yaml` file supports several advanced configuration options that let you customize Forge's behavior.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Custom Rules\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdd your own guidelines that all agents should follow when generating responses.\n\n```yaml\n# forge.yaml\ncustom_rules: |\n  1. Always add comprehensive error handling to any code you write.\n  2. Include unit tests for all new functions.\n  3. Follow our team's naming convention: camelCase for variables, PascalCase for classes.\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Commands\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nDefine custom commands as shortcuts for repetitive prompts:\n\n```yaml\n# forge.yaml\ncommands:\n  - name: \"refactor\"\n    description: \"Refactor selected code\"\n    prompt: \"Please refactor this code to improve readability and performance\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Model\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nSpecify the default AI model to use for all agents in the workflow.\n\n```yaml\n# forge.yaml\nmodel: \"claude-3.7-sonnet\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Max Walker Depth\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl how deeply Forge traverses your project directory structure when gathering context.\n\n```yaml\n# forge.yaml\nmax_walker_depth: 3 # Limit directory traversal to 3 levels deep\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Temperature\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdjust the creativity and randomness in AI responses. Lower values (0.0-0.3) produce more focused, deterministic outputs, while higher values (0.7-2.0) generate more diverse and creative results.\n\n```yaml\n# forge.yaml\ntemperature: 0.7 # Balanced creativity and focus\n```\n\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Tool Max Failure Limit\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nControl how many times a tool can fail before Forge forces completion to prevent infinite retry loops. This helps avoid situations where an agent gets stuck repeatedly trying the same failing operation.\n\n```yaml\n# forge.yaml\nmax_tool_failure_per_turn: 3 # Allow up to 3 failures per tool before forcing completion\n```\n\nSet to a higher value if you want more retry attempts, or lower if you want faster failure detection.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Max Requests Per Turn\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nLimit the maximum number of requests an agent can make in a single conversation turn. This prevents runaway conversations and helps control API usage and costs.\n\n```yaml\n# forge.yaml\nmax_requests_per_turn: 50 # Allow up to 50 requests per turn\n```\n\nWhen this limit is reached, Forge will:\n\n- Ask you if you wish to continue\n- If you respond with 'Yes', it will continue the conversation\n- If you respond with 'No', it will end the conversation\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Model Context Protocol (MCP)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nThe MCP feature allows AI agents to communicate with external tools and services. This implementation follows Anthropic's [Model Context Protocol](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Ftutorials#set-up-model-context-protocol-mcp) design.\n\n### MCP Configuration\n\nConfigure MCP servers using the CLI:\n\n```bash\n# List all MCP servers\nforge mcp list\n\n# Import a server from JSON\nforge mcp import\n\n# Show server configuration details\nforge mcp show\n\n# Remove a server\nforge mcp remove\n\n# Reload servers and rebuild caches\nforge mcp reload\n```\n\nOr manually create a `.mcp.json` file with the following structure:\n\n```json\n{\n  \"mcpServers\": {\n    \"server_name\": {\n      \"command\": \"command_to_execute\",\n      \"args\": [\"arg1\", \"arg2\"],\n      \"env\": { \"ENV_VAR\": \"value\" }\n    },\n    \"another_server\": {\n      \"url\": \"http:\u002F\u002Flocalhost:3000\u002Fevents\"\n    }\n  }\n}\n```\n\nMCP configurations are read from two locations (project-local takes precedence):\n\n1. **Project-local:** `.mcp.json` in your project directory\n2. **Global:** `~\u002Fforge\u002F.mcp.json`\n\n### Example Use Cases\n\nMCP can be used for various integrations:\n\n- Web browser automation\n- External API interactions\n- Tool integration\n- Custom service connections\n\n### Usage in Multi-Agent Workflows\n\nMCP tools can be used as part of multi-agent workflows, allowing specialized agents to interact with external systems as part of a collaborative problem-solving approach.\n\n\u003C\u002Fdetails>\n\n---\n\n## Documentation\n\nFor comprehensive documentation on all features and capabilities, please visit the [documentation site](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Ftree\u002Fmain\u002Fdocs).\n\n---\n\n## Installation\n\n```bash\n# YOLO\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n\n# Package managers\nnix run github:tailcallhq\u002Fforgecode # for latest dev branch\n```\n\n---\n\n## Community\n\nJoin our vibrant Discord community to connect with other Forge users and contributors, get help with your projects, share ideas, and provide feedback!\n\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https:\u002F\u002Fdiscord.gg\u002FkRZBPpkgwq)\n\n---\n\n## Support Us\n\nYour support drives Forge's continued evolution! By starring our GitHub repository, you:\n\n- Help others discover this powerful tool 🔍\n- Motivate our development team 💪\n- Enable us to prioritize new features 🛠️\n- Strengthen our open-source community 🌱\n","\u003Ch1 align=\"center\">⚒️ Forge：AI增强型终端开发环境\u003C\u002Fh1>\n\u003Cp align=\"center\">一个将AI能力与您的开发环境无缝集成的全面编码助手\u003C\u002Fp>\n\n\u003Cp align=\"center\">\u003Ccode>curl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\u003C\u002Fcode>\u003C\u002Fp>\n\n[![CI状态](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Ftailcallhq\u002Fforgecode\u002Fci.yml?style=for-the-badge)](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Factions)\n[![GitHub发布](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Ftailcallhq\u002Fforgecode?style=for-the-badge)](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Freleases)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https:\u002F\u002Fdiscord.gg\u002FkRZBPpkgwq)\n[![CLA助手](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fantinomyhq_forgecode_readme_5000b64aa31f.png)](https:\u002F\u002Fcla-assistant.io\u002Ftailcallhq\u002Fforgecode)\n\n![Code-Forge演示](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fantinomyhq_forgecode_readme_cb5d35c670ff.gif)\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>目录\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- [快速入门](#quickstart)\n- [使用示例](#usage-examples)\n- [为什么选择Forge？](#why-forge)\n- [Forge的工作原理：三种模式](#how-forge-works-three-modes)\n  - [交互式模式（TUI）](#interactive-mode-tui)\n  - [一次性CLI模式](#one-shot-cli-mode)\n  - [ZSH插件模式（`:`前缀）](#zsh-plugin-mode--prefix)\n- [ZSH插件：`:`前缀系统](#zsh-plugin-the--prefix-system)\n  - [代理](#agents)\n  - [发送提示](#sending-prompts)\n  - [附加文件](#attaching-files)\n  - [对话管理](#conversation-management)\n  - [Git集成](#git-integration)\n  - [Shell命令工具](#shell-command-tools)\n  - [会话与配置](#session--configuration)\n  - [技能](#skills)\n  - [自定义代理行为](#customizing-agent-behavior)\n  - [语义搜索（工作区）](#semantic-search-workspace)\n  - [快速参考：所有`:`命令](#quick-reference-all--commands)\n- [命令行选项](#command-line-options)\n- [高级配置](#advanced-configuration)\n  - [提供商配置](#provider-configuration)\n    - [管理提供商凭据](#managing-provider-credentials)\n    - [已弃用：环境变量](#deprecated-environment-variables)\n  - [forge.yaml配置选项](#forgeyaml-configuration-options)\n  - [环境变量](#environment-variables)\n  - [MCP配置](#mcp-configuration)\n  - [示例用例](#example-use-cases)\n  - [在多代理工作流中的使用](#usage-in-multi-agent-workflows)\n- [文档](#documentation)\n- [社区](#community)\n- [支持我们](#support-us)\n\n\u003C\u002Fdetails>\n\n---\n\n## 快速入门\n\n要开始使用Forge，请运行以下命令：\n\n```bash\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n```\n\n首次运行时，Forge会引导您通过交互式登录流程设置AI提供商的凭据。或者，您也可以提前配置提供商：\n\n```bash\n# 交互式配置提供商凭据\nforge provider login\n\n# 然后启动Forge\nforge\n```\n就是这样！Forge现在已准备好协助您完成开发任务。\n\n## 使用示例\n\nForge可以根据您的需求以不同方式使用。以下是一些常见的使用场景：\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>代码理解\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 能否解释一下这个代码库中的认证系统是如何工作的？\n```\n\nForge会分析您的项目结构，识别与认证相关的文件，并提供详细的认证流程说明，包括各个组件之间的关系。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>实现新功能\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 我需要为我们的React应用添加一个暗黑模式切换开关。我应该怎样入手呢？\n```\n\nForge会根据您当前的代码库提出最佳方案，解释所需步骤，甚至为您搭建必要的组件和样式。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>调试帮助\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 我遇到了这个错误：“TypeError: Cannot read property 'map' of undefined”。这可能是什么原因造成的？\n```\n\nForge会分析该错误，根据您的代码提出潜在原因，并给出不同的解决方案来修复问题。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>代码审查\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 请审查src\u002Fcomponents\u002FUserProfile.js中的代码，并提出改进建议。\n```\n\nForge会分析这段代码，找出潜在问题，并从可读性、性能、安全性及可维护性等方面提出改进建议。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>学习新技术\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 我想将GraphQL集成到这个Express应用中。你能告诉我如何开始吗？\n```\n\nForge会结合您具体的项目结构，为您提供关于如何将GraphQL与Express集成的定制化教程。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>数据库模式设计\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 我需要为一个包含用户、文章、评论和分类的博客设计数据库模式。\n```\n\nForge会根据您项目现有的数据库技术，建议合适的表\u002F集合设计、关系、索引和约束。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>重构遗留代码\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 帮我将这个基于类的组件重构为使用React Hooks的形式。\n```\n\nForge可以帮助您现代化代码库，指导您完成重构步骤，并在您确认后实施这些更改。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Git操作\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n> 我需要将分支‘feature\u002Fuser-profile’合并到main分支，但存在冲突。\n```\n\nForge可以指导您解决Git冲突，解释差异并建议最佳的协调方式。\n\n\u003C\u002Fdetails>\n\n## 为什么选择Forge？\n\nForge专为希望在保持对开发环境完全控制的同时，利用AI辅助提升工作效率的开发者而设计。\n\n- **零配置**——只需添加API密钥即可开始使用\n- **无缝集成**——直接在您常用的终端中工作\n- **多提供商支持**——支持OpenAI、Anthropic等LLM提供商\n- **安全设计**——受限的shell模式限制了文件系统的访问，防止意外更改\n- **开源**——透明、可扩展且由社区驱动\n\nForge助您更快地编写代码、解决复杂问题以及学习新技术，同时无需离开终端。\n\n---\n\n## Forge的工作原理：三种模式\n\nForge提供了三种不同的使用方式。提前了解这些区别将帮助您避免混淆。\n\n### 交互模式（TUI）\n\n不带任何参数运行 `forge` 会启动交互式终端界面，这是一个持久会话，您可以在其中输入提示，AI 会以对话循环的方式进行响应。这是执行多步骤工作的主要方式。\n\n```bash\nforge                              # 启动一个新的交互式会话\nforge conversation resume \u003Cid>     # 在交互模式下恢复特定的已保存对话\nforge --conversation-id \u003Cid>       # 同上：通过 ID 恢复对话\nforge --agent \u003Cagent-id>           # 使用特定代理启动交互式会话\nforge -C \u002Fpath\u002Fto\u002Fproject          # 在指定目录下启动\nforge --sandbox experiment-name    # 创建一个隔离的 Git 工作树 + 分支，然后在此处启动\n```\n\n进入交互模式后，输入您的提示并按 Enter 键。Forge 会读取文件、生成补丁、运行命令，并在整个会话中保持上下文。\n\n### 一次性 CLI 模式\n\n传递 `-p`（或 `--prompt`）来运行单个提示并退出。Forge 完成工作后会返回到您的 shell。这对于脚本、输出管道或快速任务非常有用。\n\n```bash\nforge -p \"解释 src\u002Fmain.rs 的作用\"\nforge -p \"在 lib.rs 中的 parse() 函数中添加错误处理\"\necho \"这是做什么的？\" | forge    # 将输入作为提示传递\nforge commit                         # 生成 AI 提交信息并提交（完成后退出）\nforge commit --preview               # 生成提交信息，打印出来后退出\nforge suggest \"查找大型日志文件\" # 将自然语言翻译为 Shell 命令，然后退出\n```\n\n> **注意：** `forge conversation resume \u003Cid>` 会打开交互式 TUI。它**不会**只是打印一条消息就退出。如果您运行该命令后看到光标在等待输入，说明您已经进入了交互式会话。您可以输入提示，或者按 `Ctrl+C` 退出。\n\n### ZSH 插件模式（`:` 前缀）\n\n使用 `forge setup` 安装一次 ZSH 插件后，您就可以直接在 shell 提示符下使用 `:` 命令，而无需每次都输入 `forge`。这是日常开发中最快速的模式：发送提示、切换对话、提交代码以及建议命令，全程无需离开 shell。\n\n```zsh\n: 重构认证模块      # 向当前活跃的代理发送提示\n:commit                         # AI 驱动的 Git 提交\n:suggest \"查找大型日志文件\" # 将描述转换为 Shell 命令并插入到您的缓冲区\n:conversation                   # 使用 fzf 预览浏览已保存的对话\n```\n\n有关所有命令和别名，请参阅下方的[完整 ZSH 插件参考](#zsh-plugin-the--prefix-system)。\n\n---\n\n## ZSH 插件：`:` 前缀系统\n\n当您安装 ZSH 插件（`forge setup`）后，您的 shell 提示符上就会出现 `:` 前缀命令系统。这是在正常开发过程中使用 Forge 的最快方式；您始终无需离开 shell。\n\n**工作原理：** 以 `:` 开头的行会在 shell 处理之前被截获，并路由到 Forge。其余内容则按正常方式执行。\n\n```zsh\n: \u003Cprompt>         # 向当前活跃的代理发送提示\n:sage \u003Cprompt>     # 向特定名称的代理发送提示（sage、muse、forge 或任何自定义代理）\n:agent \u003Cname>      # 切换当前活跃的代理；如果未指定名称，则打开 fzf 选择器\n```\n\n### 代理\n\nForge 自带三个内置代理，每个代理都有不同的角色：\n\n| 代理 | 别名 | 用途 | 修改文件吗？ |\n|---|---|---|---|\n| `forge` | （默认） | 实现：构建功能、修复 bug 和运行测试 | 是 |\n| `sage` | `:ask` | 研究：绘制架构图、追踪数据流和阅读代码 | 否 |\n| `muse` | `:plan` | 规划：分析结构并将实现计划写入 `plans\u002F` 目录 | 否 |\n\n### 发送提示\n\n```zsh\n: 将认证模块重构为使用新的中间件\n:sage 缓存层是如何工作的？    # sage = 只读研究代理\n:muse 设计一个部署策略        # muse = 规划代理（写入 plans\u002F 目录）\n:ask X 是如何工作的？                     # :sage 的别名\n:plan 制定一个迁移计划             # :muse 的别名\n```\n\n代理上下文是持久化的。单独输入 `:sage`（没有提示文本）会将当前活跃的代理切换为 sage，后续的所有 `: \u003Cprompt>` 命令都会使用 sage 代理。\n\n### 附加文件\n\n在提示中输入 `@`，然后按 Tab 键进行模糊搜索并选择文件。路径会被插入为 `@[filename]`，并作为上下文附加给 AI。\n\n```zsh\n: 审查这段代码 @[src\u002Fauth.rs] @[tests\u002Fauth_test.rs]\n```\n\n### 对话管理\n\nForge 会保存每一次对话。您可以像切换目录一样在不同对话之间切换。\n\n```zsh\n:new                      # 开始一个新的对话（保存当前对话以便于 :conversation - 使用）\n:new \u003Cinitial prompt>     # 开始一个新的对话并立即发送提示\n:conversation             # 打开 fzf 选择器：浏览并切换对话，带有预览\n:conversation \u003Cid>        # 直接通过 ID 切换到某个对话\n:conversation -           # 在当前对话和上一个对话之间切换（类似于 cd -）\n:clone                    # 分支当前对话（尝试不同的方向）\n:clone \u003Cid>               # 通过 ID 克隆特定对话\n:rename \u003Cname>            # 重命名当前对话\n:conversation-rename      # 通过 fzf 选择器重命名对话\n:retry                    # 重试上次的提示（当 AI 理解有误时很有用）\n:copy                     # 将上次 AI 的回复复制到剪贴板，格式为 Markdown\n:dump                     # 将对话导出为 JSON 格式\n:dump html                # 将对话导出为格式化的 HTML\n:compact                  # 手动压缩上下文，以释放 token 预算\n```\n\n### Git 集成\n\n```zsh\n:commit                   # AI 读取您的 diff，生成提交信息并立即提交\n:commit \u003Ccontext>         # 同上，但可以传递额外的上下文：:commit 修复 README 中的拼写错误\n:commit-preview           # AI 生成提交信息，并将 \"git commit -m '...'\" 放入您的缓冲区\n                          # 这样您可以在按下 Enter 键前先查看或编辑提交信息\n```\n\n### Shell 命令工具\n\n```zsh\n:suggest \u003Cdescription>    # 将自然语言翻译为 Shell 命令并放入您的缓冲区\n:edit                     # 打开 $EDITOR 编写复杂的多行提示，然后发送\n```\n\n### 会话与配置\n\n有些命令仅更改当前会话的设置，而另一些则会持久化到您的配置文件（`~\u002Fforge\u002F.forge.toml`）。这两者是有区别的：\n\n```zsh\n# 仅限会话（关闭终端时重置，不会保存到配置文件）\n:model \u003Cmodel-id>              # 仅为此会话更改模型\n:reasoning-effort \u003Clevel>      # 设置推理力度：无\u002F极低\u002F低\u002F中\u002F高\u002F极高\u002F最大\n:agent \u003Cid>                    # 为此会话切换活跃代理\n\n# 持久化（保存到配置文件）\n:config-model \u003Cmodel-id>       # 全局设置默认模型  (别名: :cm)\n:config-provider               # 全局切换提供商    (别名: :provider, :p)\n:config-reasoning-effort \u003Clvl> # 全局设置默认推理力度 (别名: :cre)\n:config-commit-model \u003Cid>      # 设置用于 :commit 的模型  (别名: :ccm)\n:config-suggest-model \u003Cid>     # 设置用于 :suggest 的模型 (别名: :csm)\n:config-reload                 # 将会话覆盖重置为全局配置 (别名: :cr)\n\n# 查看与编辑配置\n:info                          # 显示当前会话信息（模型、代理、对话 ID）\n:config                        # 以 TOML 格式显示生效的解析后配置\n:config-edit                   # 在 $EDITOR 中打开配置文件 (别名: :ce)\n:tools                         # 列出当前代理可用的工具\n:skill                         # 列出可用技能\n```\n\n### 技能\n\n技能是 AI 可以作为工具调用的可复用工作流。Forge 预装了三种内置技能：\n\n- **`create-skill`**：搭建一个新的自定义技能\n- **`execute-plan`**：执行 `plans\u002F` 目录下的计划文件\n- **`github-pr-description`**：根据你的代码差异生成 PR 描述\n\n使用 `:skill` 可以列出可用技能。AI 会在相关时自动调用这些技能，你也可以明确请求：`: 使用 github-pr-description 技能生成 PR 描述`。\n\n**自定义技能** 存在于带有 YAML 前言的 `SKILL.md` 文件中。优先级（最高优先）如下：\n\n| 位置           | 路径                           | 范围         |\n|----------------|--------------------------------|--------------|\n| 项目本地       | `.forge\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | 仅限该项目   |\n| 全局           | `~\u002Fforge\u002Fskills\u002F\u003Cname>\u002FSKILL.md` | 所有项目     |\n| 内置           | 嵌入二进制文件中               | 始终可用     |\n\n项目本地技能会覆盖全局技能，而全局技能又会覆盖内置技能。要搭建新技能，请输入：`: 创建一个新技能`。\n\n### 自定义代理行为\n\n**`AGENTS.md`：** 在你的项目根目录下创建此文件（或在 `~\u002Fforge\u002FAGENTS.md` 全局范围内），为所有代理提供持久化的指令，例如编码规范、提交信息风格以及需要避免的内容。Forge 会在每次对话开始时自动读取该文件。\n\n**自定义代理：** 将带有 YAML 前言的 `.md` 文件放置在 `.forge\u002Fagents\u002F`（项目级别）或 `~\u002Fforge\u002Fagents\u002F`（全局级别），以定义具有各自模型、工具和系统提示的额外代理。项目级别的代理会覆盖全局代理。位于 `crates\u002Fforge_repo\u002Fsrc\u002Fagents\u002F` 的内置代理文件是该格式的良好示例。\n\n**自定义命令：** 将 YAML 文件放置在 `.forge\u002Fcommands\u002F`（项目级别）或 `~\u002Fforge\u002Fcommands\u002F`（全局级别），以定义可通过 `:commandname` 调用的快捷命令。命令也可以直接在 `forge.yaml` 的 `commands:` 键下内联定义。\n\n### 语义搜索（工作区）\n\n```zsh\n:sync                     # 为语义搜索索引你的代码库\n:workspace-init           # 初始化工作区以进行索引\n:workspace-status         # 显示索引状态\n:workspace-info           # 显示工作区详情\n```\n\n运行 `:sync` 后，AI 可以根据语义而非精确文本匹配来搜索你的代码库。索引过程会将文件内容发送到工作区服务器，默认地址为 `https:\u002F\u002Fapi.forgecode.dev`。如果选择自托管，可以设置 `FORGE_WORKSPACE_SERVER_URL` 来覆盖此默认值。\n\n### 快速参考：所有 `:` 命令\n\n\n| 命令        | 别名 | 功能                                                         |\n|-------------|------|--------------------------------------------------------------|\n| `: \u003Cprompt>` |      | 将提示发送给活跃代理                                         |\n| `:new`      | `:n` | 开始新的对话                                                 |\n| `:conversation` | `:c` | 浏览\u002F切换对话（通过 fzf）                                   |\n| `:conversation -` |      | 切换到上一个对话                                             |\n| `:clone`    |      | 分支当前对话                                                 |\n| `:rename \u003Cname>` | `:rn` | 重命名当前对话                                               |\n| `:conversation-rename` |      | 重命名对话（通过 fzf 选择器）                               |\n| `:retry`    | `:r` | 重试上次的提示                                               |\n| `:copy`     |      | 将上次的回答复制到剪贴板                                     |\n| `:dump`     | `:d` | 将对话导出为 JSON                                            |\n| `:compact`  |      | 紧缩上下文                                                   |\n| `:commit`   |      | AI 即时提交                                                  |\n| `:commit-preview` |      | AI 提交（先预览）                                            |\n| `:suggest \u003Cdesc>` | `:s` | 将自然语言翻译成命令                                         |\n| `:edit`     | `:ed` | 在 $EDITOR 中编写提示                                         |\n| `:sage \u003Cprompt>` | `:ask` | 问答 \u002F 代码理解代理                                          |\n| `:muse \u003Cprompt>` | `:plan` | 规划代理                                                     |\n| `:agent \u003Cname>` | `:a` | 切换活跃代理（若未指定名称，则通过 fzf 选择器）             |\n| `:model \u003Cid>` | `:m` | 仅为此会话设置模型                                           |\n| `:config-model \u003Cid>` | `:cm` | 设置默认模型（持久化）                                       |\n| `:reasoning-effort \u003Clvl>` | `:re` | 设置会话的推理力度                                           |\n| `:config-reload` | `:cr` | 将会话覆盖重置为全局配置                                     |\n| `:info`     | `:i` | 显示会话信息                                                 |\n| `:sync`     | `:workspace-sync` | 为语义搜索索引代码库                                         |\n| `:tools`    | `:t` | 列出可用工具                                                 |\n| `:skill`    |      | 列出可用技能                                                 |\n| `:login`    | `:provider-login` | 登录到某个提供商                                             |\n| `:logout`   |      | 从某个提供商登出                                             |\n| `:keyboard-shortcuts` | `:kb` | 显示键盘快捷键                                               |\n| `:doctor`   |      | 运行 Shell 环境诊断                                          |\n\n---\n\n## 命令行选项\n\n以下是 Forge 命令行选项的快速参考：\n\n| 选项                              | 描述                                                              |\n| ----------------------------------- | ------------------------------------------------------------------------ |\n| `-p, --prompt \u003CPROMPT>`             | 直接传递提示，无需进入交互模式                                       |\n| `-e, --event \u003CEVENT>`               | 以 JSON 格式向工作流分发事件                                         |\n| `--conversation \u003CCONVERSATION>`     | 包含要执行的对话的 JSON 文件路径                                     |\n| `--conversation-id \u003CID>`            | 根据 ID 恢复或继续现有对话                                           |\n| `--agent \u003CAGENT>`                   | 本次会话使用的代理 ID                                                |\n| `-C, --directory \u003CDIR>`             | 在启动前切换到此目录                                                 |\n| `--sandbox \u003CNAME>`                  | 创建隔离的 Git 工作树 + 分支，用于安全实验                           |\n| `--verbose`                         | 启用详细日志输出                                                     |\n| `-h, --help`                        | 打印帮助信息                                                         |\n| `-V, --version`                     | 打印版本                                                             |\n\n### 子命令\n\n```bash\n\n# 对话\nforge conversation list                  # 列出所有已保存的对话\nforge conversation resume \u003Cid>           # 以交互模式恢复对话\nforge conversation new                   # 创建一个新的对话 ID（并打印）\nforge conversation dump \u003Cid>             # 将对话导出为 JSON 格式\nforge conversation compact \u003Cid>          # 精简对话上下文\nforge conversation retry \u003Cid>            # 重试上一条消息\nforge conversation clone \u003Cid>            # 克隆一个对话\nforge conversation rename \u003Cid> \u003Cname>    # 重命名对话\nforge conversation delete \u003Cid>           # 永久删除对话\nforge conversation info \u003Cid>             # 显示对话详情\nforge conversation stats \u003Cid>            # 显示 token 使用统计\nforge conversation show \u003Cid>             # 显示最后一条助手消息\n\n# 提交\nforge commit                             # 生成 AI 提交信息并提交\nforge commit --preview                   # 仅生成提交信息（并打印）\nforge commit fix the auth bug            # 为提交信息传递额外上下文\n\n# Shell 命令建议\nforge suggest \"list files by size\"       # 将描述转换为 shell 命令\n\n# 供应商\nforge provider login                     # 添加或更新供应商凭据（交互式）\nforge provider logout                    # 移除供应商凭据\nforge list provider                      # 列出支持的供应商\n\n# 模型与代理\nforge list model                         # 列出可用模型\nforge list agent                         # 列出可用代理\n\n# 工作区 \u002F 语义搜索\nforge workspace sync                     # 为语义搜索索引当前目录\nforge workspace init                     # 初始化工作区\nforge workspace status                   # 显示索引状态\nforge workspace query \u003Ctext>             # 查询语义索引\n\n# MCP 服务器\nforge mcp list                           # 列出已配置的 MCP 服务器\nforge mcp import                         # 从 JSON 添加服务器\nforge mcp show                           # 显示服务器配置\nforge mcp remove                         # 移除服务器\nforge mcp reload                         # 重新加载所有服务器并重建缓存\n\n# 其他\nforge info                               # 显示配置、当前使用的模型和环境\nforge list tool --agent \u003Cid>             # 列出特定代理可用的工具\nforge doctor                             # 运行 shell 环境诊断\nforge update                             # 更新 forge 到最新版本\nforge setup                              # 安装 ZSH 插件（更新 .zshrc）\n```\n\n## 高级配置\n\n### 供应商配置\n\nForge 支持多个 AI 供应商。推荐使用交互式登录命令来配置供应商：\n\n```bash\nforge provider login\n```\n\n该命令会执行以下操作：\n\n1. 显示可用的供应商列表\n2. 引导您输入所需的凭据\n\n#### 管理供应商凭据\n\n```bash\n# 登录供应商（添加或更新凭据）\nforge provider login\n\n# 移除供应商凭据\nforge provider logout\n\n# 列出支持的供应商\nforge provider list\n```\n\n#### 已弃用：环境变量\n\n> **⚠️ 已弃用**：使用 `.env` 文件进行供应商配置已被弃用，并将在未来版本中移除。请改用 `forge provider login`。\n\n出于向后兼容性考虑，Forge 仍支持环境变量。首次运行时，任何在环境变量中找到的凭据都会自动迁移到基于文件的存储中。\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>旧版环境变量设置（已弃用）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenRouter\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENROUTER_API_KEY=\u003Cyour_openrouter_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Requesty\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nREQUESTY_API_KEY=\u003Cyour_requesty_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>x-ai\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nXAI_API_KEY=\u003Cyour_xai_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>z.ai\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nZAI_API_KEY=\u003Cyour_zai_api_key>\n\n# 或者用于编码计划订阅\nZAI_CODING_API_KEY=\u003Cyour_zai_coding_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Cerebras\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nCEREBRAS_API_KEY=\u003Cyour_cerebras_api_key>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>IO Intelligence\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nIO_INTELLIGENCE_API_KEY=\u003Cyour_io_intelligence_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: meta-llama\u002FLlama-3.3-70B-Instruct\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>OpenAI\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_openai_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: o3-mini-high\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Anthropic\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nANTHROPIC_API_KEY=\u003Cyour_anthropic_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: claude-3.7-sonnet\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Google Vertex AI\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**设置说明：**\n\n1. **安装 Google Cloud CLI** 并进行身份验证：\n\n   ```bash\n   gcloud auth login\n   gcloud config set project YOUR_PROJECT_ID\n   ```\n\n2. **获取身份验证令牌**：\n\n   ```bash\n   gcloud auth print-access-token\n   ```\n\n3. **在 Forge 中登录时使用该令牌**：\n\n   ```bash\n   forge provider login\n   # 选择 Google Vertex AI 并输入您的凭据\n   ```\n\n**旧版 `.env` 设置：**\n\n```bash\n# .env\nPROJECT_ID=\u003Cyour_project_id>\nLOCATION=\u003Cyour_location>\nVERTEX_AI_AUTH_TOKEN=\u003Cyour_auth_token>\n```\n\n```yaml\n# forge.yaml\nmodel: google\u002Fgemini-2.5-pro\n```\n\n**可用模型：**\n- Claude 系列模型：`claude-sonnet-4@20250514`\n- Gemini 系列模型：`gemini-2.5-pro`、`gemini-2.0-flash`\n\n您可以使用 Forge CLI 中的 `\u002Fmodel` 命令查看所有可用模型。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>兼容 OpenAI 的供应商\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_provider_api_key>\nOPENAI_URL=\u003Cyour_provider_url>\n```\n\n```yaml\n# forge.yaml\nmodel: \u003C供应商特定的模型>\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Groq\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_groq_api_key>\nOPENAI_URL=https:\u002F\u002Fapi.groq.com\u002Fopenai\u002Fv1\n```\n\n```yaml\n\n# forge.yaml\nmodel: deepseek-r1-distill-llama-70b\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Amazon Bedrock\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n要使用 Amazon Bedrock 模型与 Forge 配合，您需要先设置 [Bedrock 访问网关](https:\u002F\u002Fgithub.com\u002Faws-samples\u002Fbedrock-access-gateway)：\n\n1. **设置 Bedrock 访问网关**：\n\n   - 按照 [Bedrock 访问网关仓库](https:\u002F\u002Fgithub.com\u002Faws-samples\u002Fbedrock-access-gateway) 中的部署步骤操作\n   - 在 Secrets Manager 中创建您自己的 API 密钥\n   - 部署 CloudFormation 堆栈\n   - 从 CloudFormation 输出中记下您的 API 基础 URL\n\n2. **在 Forge 中配置**：\n\n   ```bash\n   forge provider login\n   # 选择兼容 OpenAI 的提供商，并输入您的 Bedrock 网关详细信息\n   ```\n\n**旧版 `.env` 设置：**\n\n```bash\n# .env\nOPENAI_API_KEY=\u003Cyour_bedrock_gateway_api_key>\nOPENAI_URL=\u003Cyour_bedrock_gateway_base_url>\n```\n\n```yaml\n# forge.yaml\nmodel: anthropic.claude-3-opus\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>ForgeCode 服务\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# .env\nFORGE_API_KEY=\u003Cyour_forge_api_key>\n```\n\n```yaml\n# forge.yaml\nmodel: claude-3.7-sonnet\n```\n\n\u003C\u002Fdetails>\n\n\u003C\u002Fdetails>\n\n---\n\n### forge.yaml 配置选项\n\n### 环境变量\n\nForge 支持多个环境变量，用于高级配置和微调。这些变量可以在您的 `.env` 文件或系统环境中设置。\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>重试配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n控制 Forge 如何处理失败请求的重试逻辑：\n\n```bash\n# .env\nFORGE_RETRY_INITIAL_BACKOFF_MS=1000    # 初始退避时间，单位为毫秒（默认值：1000）\nFORGE_RETRY_BACKOFF_FACTOR=2           # 退避时间的倍数因子（默认值：2）\nFORGE_RETRY_MAX_ATTEMPTS=3             # 最大重试次数（默认值：3）\nFORGE_SUPPRESS_RETRY_ERRORS=false      # 是否抑制重试错误信息（默认值：false）\nFORGE_RETRY_STATUS_CODES=429,500,502   # 需要重试的 HTTP 状态码（默认值：429、500、502、503、504）\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>HTTP 配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n微调 API 请求的 HTTP 客户端行为：\n\n```bash\n# .env\nFORGE_HTTP_CONNECT_TIMEOUT=30              # 连接超时时间，单位为秒（默认值：30）\nFORGE_HTTP_READ_TIMEOUT=900                # 读取超时时间，单位为秒（默认值：900）\nFORGE_HTTP_POOL_IDLE_TIMEOUT=90            # 池空闲超时时间，单位为秒（默认值：90）\nFORGE_HTTP_POOL_MAX_IDLE_PER_HOST=5        # 每个主机的最大空闲连接数（默认值：5）\nFORGE_HTTP_MAX_REDIRECTS=10                # 最大可跟随的重定向次数（默认值：10）\nFORGE_HTTP_USE_HICKORY=false               # 是否使用 Hickory DNS 解析器（默认值：false）\nFORGE_HTTP_TLS_BACKEND=default             # TLS 后端：“default” 或 “rustls”（默认值：“default”）\nFORGE_HTTP_MIN_TLS_VERSION=1.2             # 最低 TLS 版本：“1.0”、“1.1”、“1.2”、“1.3”\nFORGE_HTTP_MAX_TLS_VERSION=1.3             # 最高 TLS 版本：“1.0”、“1.1”、“1.2”、“1.3”\nFORGE_HTTP_ADAPTIVE_WINDOW=true            # 是否启用 HTTP\u002F2 自适应窗口（默认值：true）\nFORGE_HTTP_KEEP_ALIVE_INTERVAL=60          # 长连接保持活动的时间间隔，单位为秒（默认值：60；使用“none”或“disabled”可禁用）\nFORGE_HTTP_KEEP_ALIVE_TIMEOUT=10           # 长连接保持活动的超时时间，单位为秒（默认值：10）\nFORGE_HTTP_KEEP_ALIVE_WHILE_IDLE=true      # 在空闲时保持长连接（默认值：true）\nFORGE_HTTP_ACCEPT_INVALID_CERTS=false      # 是否接受无效证书（默认值：false）——请谨慎使用\nFORGE_HTTP_ROOT_CERT_PATHS=\u002Fpath\u002Fto\u002Fcert1.pem,\u002Fpath\u002Fto\u002Fcert2.crt  # 根证书文件路径（PEM、CRT、CER 格式），多个路径用逗号分隔\n```\n\n> **⚠️ 安全警告**：将 `FORGE_HTTP_ACCEPT_INVALID_CERTS=true` 设置为开启状态会禁用 SSL\u002FTLS 证书验证，这会使您面临中间人攻击的风险。请仅在开发环境或完全信任网络及端点的情况下使用此设置。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>API 配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n覆盖默认的 API 端点以及提供商和模型设置：\n\n```bash\n# .env\nFORGE_API_URL=https:\u002F\u002Fapi.forgecode.dev  # 自定义 Forge API URL（默认值：https:\u002F\u002Fapi.forgecode.dev）\nFORGE_WORKSPACE_SERVER_URL=http:\u002F\u002Flocalhost:8080  # 索引服务器的 URL（默认值：https:\u002F\u002Fapi.forgecode.dev\u002F）\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>工具配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n配置工具调用的相关设置：\n\n```bash\n# .env\nFORGE_TOOL_TIMEOUT=300         # 工具执行的最大时间限制，超过该时间将终止工具运行，以防止会话卡死。（默认值：300 秒）\nFORGE_MAX_IMAGE_SIZE=10485760  # read_image 操作允许的最大图片文件大小，单位为字节（默认值：10485760 字节，即 10 MB）\nFORGE_DUMP_AUTO_OPEN=false     # 是否自动在浏览器中打开转储文件（默认值：false）\nFORGE_DEBUG_REQUESTS=\u002Fpath\u002Fto\u002Fdebug\u002Frequests.json  # 将调试 HTTP 请求文件写入指定路径（支持绝对路径和相对路径）\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>ZSH 插件配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n配置 ZSH 插件的行为：\n\n```bash\n# .env\nFORGE_BIN=forge                    # 用于执行 Forge 操作的命令（默认值：“forge”）\n```\n\n`FORGE_BIN` 环境变量允许您自定义 ZSH 插件在处理以 `:` 开头的命令时使用的命令。如果未设置，则默认为“forge”。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>显示配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n配置 Forge UI 和 ZSH 主题的显示选项：\n\n```bash\n# .env\nFORGE_CURRENCY_SYMBOL=\"$\"         # ZSH 主题中成本显示的货币符号（默认值：“$”）\nFORGE_CURRENCY_CONVERSION_RATE=1.0  # 货币转换率（默认值：1.0）\nNERD_FONT=1                       # 在 ZSH 主题中启用 Nerd Font 图标（默认值：自动检测；设置为“1”或“true”启用，设置为“0”或“false”禁用）\nUSE_NERD_FONT=1                   # 启用 Nerd Font 图标的替代变量（与 NERD_FONT 行为相同）\n```\n\n`FORGE_CURRENCY_SYMBOL` 和 `FORGE_CURRENCY_CONVERSION_RATE` 变量控制着 ZSH 主题右提示符中成本的显示方式。您可以使用这些变量来自定义适合您所在地区或偏好的货币显示格式。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>系统配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n系统级别的环境变量（通常由系统自动设置）：\n\n```bash\n\n# .env\nFORGE_CONFIG=\u002Fcustom\u002Fconfig\u002Fdir        # 所有 Forge 配置文件的基础目录（默认：~\u002F.forge）\nFORGE_MAX_SEARCH_RESULT_BYTES=10240   # 搜索结果的最大字节数（默认：10240 - 10 KB）\nFORGE_HISTORY_FILE=\u002Fpath\u002Fto\u002Fhistory    # Forge 历史文件的自定义路径（默认：使用系统默认位置）\nFORGE_BANNER=\"Your custom banner text\" # 启动时显示的自定义横幅文本（默认：Forge ASCII 艺术）\nFORGE_MAX_CONVERSATIONS=100            # 列表中最多显示的对话数量（默认：100）\nFORGE_MAX_LINE_LENGTH=2000             # 文件读取操作每行的最大字符数（默认：2000）\nFORGE_STDOUT_MAX_LINE_LENGTH=2000      # shell 输出每行的最大字符数（默认：2000）\nSHELL=\u002Fbin\u002Fzsh                         # 用于执行命令的 shell（Unix\u002FLinux\u002FmacOS）\nCOMSPEC=cmd.exe                        # 用于执行命令的处理器（Windows）\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>语义搜索配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n配置代码理解的语义搜索行为：\n\n```bash\n# .env\nFORGE_SEM_SEARCH_LIMIT=200            # 初始向量搜索返回的最大结果数（默认：200）\nFORGE_SEM_SEARCH_TOP_K=20             # 语义搜索过程中用于相关性过滤的 top-k 参数（默认：20）\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>日志配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n配置日志的详细程度和输出：\n\n```bash\n# .env\nFORGE_LOG=forge=info                  # 日志筛选级别（默认：跟踪关闭时为 forge=debug，开启时为 forge=info）\n```\n\n`FORGE_LOG` 变量使用标准的追踪过滤器语法来控制 Forge 内部操作的日志级别。常见值：\n- `forge=error` - 仅记录错误\n- `forge=warn` - 记录警告和错误\n- `forge=info` - 记录信息性消息（跟踪开启时的默认值）\n- `forge=debug` - 记录调试信息（跟踪关闭时的默认值）\n- `forge=trace` - 记录详细的追踪信息\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>跟踪配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n控制遥测事件中用户识别元数据的跟踪：\n\n```bash\n# .env\nFORGE_TRACKER=false                   # 禁用跟踪增强元数据（默认：true）\n```\n\n`FORGE_TRACKER` 变量控制是否在遥测事件中包含跟踪增强元数据。\n\n\u003C\u002Fdetails>\n\n`forge.yaml` 文件支持多个高级配置选项，允许您自定义 Forge 的行为。\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>自定义规则\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n添加所有代理在生成响应时应遵循的指导原则。\n\n```yaml\n# forge.yaml\ncustom_rules: |\n  1. 您编写的任何代码都必须始终包含全面的错误处理。\n  2. 所有新函数都应包含单元测试。\n  3. 遵循我们团队的命名规范：变量使用驼峰命名法，类使用帕斯卡命名法。\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>命令\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n将重复性提示定义为自定义命令快捷方式：\n\n```yaml\n# forge.yaml\ncommands:\n  - name: \"refactor\"\n    description: \"重构选定的代码\"\n    prompt: \"请重构这段代码以提高可读性和性能\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>模型\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n指定工作流中所有代理使用的默认 AI 模型。\n\n```yaml\n# forge.yaml\nmodel: \"claude-3.7-sonnet\"\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>最大遍历深度\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n控制 Forge 在收集上下文时对项目目录结构的遍历深度。\n\n```yaml\n# forge.yaml\nmax_walker_depth: 3 # 将目录遍历限制在 3 层深度\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>温度\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n调整 AI 响应中的创造性和随机性。较低的值（0.0-0.3）会产生更专注、确定性的输出，而较高的值（0.7-2.0）则会生成更多样化和更具创意的成果。\n\n```yaml\n# forge.yaml\ntemperature: 0.7 # 平衡创造性和专注度\n```\n\n\u003C\u002Fdetails>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>工具最大失败次数限制\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n控制工具在 Forge 强制完成之前可以失败的次数，以防止无限重试循环。这有助于避免代理反复尝试同一失败操作而陷入僵局的情况。\n\n```yaml\n# forge.yaml\nmax_tool_failure_per_turn: 3 # 允许每个工具在强制完成前最多失败 3 次\n```\n\n如果您希望有更多的重试机会，可以将其设置为更高的值；如果希望更快地检测到失败，则可以设置为更低的值。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>每轮最大请求次数\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n限制代理在单次对话轮次中可以发出的最大请求数量。这可以防止对话失控，并有助于控制 API 使用和成本。\n\n```yaml\n# forge.yaml\nmax_requests_per_turn: 50 # 每轮最多允许 50 次请求\n```\n\n当达到此限制时，Forge 将：\n\n- 询问您是否希望继续\n- 如果您回答“是”，将继续对话\n- 如果您回答“否”，将结束对话\n\n\u003C\u002Fdetails>\n\n---\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>模型上下文协议 (MCP)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nMCP 功能允许 AI 代理与外部工具和服务进行通信。此实现遵循 Anthropic 的 [模型上下文协议](https:\u002F\u002Fdocs.anthropic.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Ftutorials#set-up-model-context-protocol-mcp) 设计。\n\n### MCP 配置\n\n使用 CLI 配置 MCP 服务器：\n\n```bash\n# 列出所有 MCP 服务器\nforge mcp list\n\n# 从 JSON 导入服务器\nforge mcp import\n\n# 显示服务器配置详情\nforge mcp show\n\n# 移除服务器\nforge mcp remove\n\n# 重新加载服务器并重建缓存\nforge mcp reload\n```\n\n或者手动创建一个 `.mcp.json` 文件，其结构如下：\n\n```json\n{\n  \"mcpServers\": {\n    \"server_name\": {\n      \"command\": \"command_to_execute\",\n      \"args\": [\"arg1\", \"arg2\"],\n      \"env\": { \"ENV_VAR\": \"value\" }\n    },\n    \"another_server\": {\n      \"url\": \"http:\u002F\u002Flocalhost:3000\u002Fevents\"\n    }\n  }\n}\n```\n\nMCP 配置从两个位置读取（项目本地优先）：\n\n1. **项目本地：** 您项目目录中的 `.mcp.json`\n2. **全局：** `~\u002Fforge\u002F.mcp.json`\n\n### 示例用例\n\nMCP 可用于各种集成场景：\n\n- 网页浏览器自动化\n- 外部 API 交互\n- 工具集成\n- 自定义服务连接\n\n### 在多代理工作流中的使用\n\nMCP 工具可以用作多代理工作流的一部分，使专业代理能够与外部系统交互，从而以协作的方式解决问题。\n\n\u003C\u002Fdetails>\n\n---\n\n## 文档\n\n有关所有功能和特性的完整文档，请访问 [文档网站](https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Ftree\u002Fmain\u002Fdocs)。\n\n---\n\n## 安装\n\n```bash\n# YOLO\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n\n# 包管理器\nnix run github:tailcallhq\u002Fforgecode # 获取最新开发分支\n```\n\n---\n\n## 社区\n\n加入我们活跃的Discord社区，与其他Forge用户和贡献者交流互动，获取项目帮助、分享创意并提供反馈吧！\n\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1044859667798568962?style=for-the-badge&cacheSeconds=120&logo=discord)](https:\u002F\u002Fdiscord.gg\u002FkRZBPpkgwq)\n\n---\n\n## 支持我们\n\n您的支持是Forge持续发展的动力！通过给我们的GitHub仓库点星，您将：\n\n- 帮助更多人发现这款强大的工具 🔍\n- 激励我们的开发团队 💪\n- 让我们能够优先开发新功能 🛠️\n- 巩固我们的开源社区 🌱","# Forge 快速上手指南\n\nForge 是一款增强型终端开发环境，它将 AI 能力无缝集成到您的工作流中，帮助您在终端内直接进行代码理解、功能实现、调试和重构。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**：macOS 或 Linux (Windows 用户建议使用 WSL2)。\n*   **Shell 环境**：推荐使用 `zsh` 以启用高效的 `:` 前缀命令系统（也支持 bash）。\n*   **网络环境**：需要能够访问外部 API（如 OpenAI, Anthropic 等）。\n    *   *提示：国内用户若遇到安装脚本下载缓慢，可尝试配置代理或使用国内镜像源下载脚本后本地执行。*\n*   **API 密钥**：准备好您常用的 LLM 提供商（如 OpenAI, Anthropic）的 API Key。\n\n## 安装步骤\n\n### 1. 一键安装\n\n打开终端，运行以下命令下载安装脚本并执行：\n\n```bash\ncurl -fsSL https:\u002F\u002Fforgecode.dev\u002Fcli | sh\n```\n\n> **注意**：如果下载速度慢，您可以先手动下载脚本内容，保存为 `install.sh`，然后运行 `sh install.sh`。\n\n### 2. 配置 AI 提供商\n\n安装完成后，首次运行时 Forge 会引导您进行交互式登录。您也可以手动配置：\n\n```bash\n# 交互式配置提供商凭证\nforge provider login\n\n# 或者直接在启动时配置\nforge\n```\n\n按照屏幕提示输入您的 API Key 即可完成设置。\n\n### 3. (可选) 启用 ZSH 插件\n\n为了获得最佳体验（使用 `:` 快捷命令），建议初始化 ZSH 插件：\n\n```bash\nforge setup\n```\n\n*执行后请重启终端或运行 `source ~\u002F.zshrc` 使插件生效。*\n\n## 基本使用\n\nForge 提供三种主要使用模式，您可以根据需求灵活切换。\n\n### 模式一：交互式终端界面 (TUI)\n\n这是最常用的模式，适合多轮对话、复杂任务处理和上下文保持。\n\n**启动命令：**\n```bash\nforge\n```\n\n**使用示例：**\n进入界面后，直接输入自然语言指令：\n*   `Can you explain how the authentication system works in this codebase?` (解释认证系统)\n*   `I need to add a dark mode toggle to our React application.` (添加深色模式)\n*   `Review the code in src\u002Fcomponents\u002FUserProfile.js` (代码审查)\n\n### 模式二：单次命令行模式 (One-Shot CLI)\n\n适合脚本集成、快速查询或生成一次性结果。\n\n**使用命令：**\n```bash\n# 直接执行提示词并退出\nforge -p \"Explain the purpose of src\u002Fmain.rs\"\n\n# 生成 AI 提交信息并自动提交\nforge commit\n\n# 将自然语言转换为 Shell 命令（仅打印，不执行）\nforge suggest \"find large log files\"\n```\n\n### 模式三：ZSH 插件模式 (`:` 前缀)\n\n如果您完成了 `forge setup`，可以直接在 Shell 提示符下使用 `:` 开头命令，无需输入 `forge`，效率极高。\n\n**常用命令：**\n\n*   **发送指令**：\n    ```zsh\n    : refactor the auth module\n    ```\n*   **切换智能体 (Agent)**：\n    *   `:ask` 或 `:sage`：切换到研究模式（只读，分析架构）。\n    *   `:plan` 或 `:muse`：切换到规划模式（生成实施计划）。\n    *   `:agent`：通过菜单选择智能体。\n*   **附加文件上下文**：\n    在指令中输入 `@` 并按 `Tab` 键，可模糊搜索并附加文件：\n    ```zsh\n    : review this code @[src\u002Fauth.rs]\n    ```\n*   **Git 操作**：\n    ```zsh\n    :commit          # AI 生成提交信息并提交\n    :conversation    # 浏览历史对话记录\n    ```\n\n---\n**小贴士**：\n*   Forge 默认包含三个智能体：**forge** (默认，负责编码和修改文件)、**sage** (负责研究和阅读)、**muse** (负责规划)。\n*   所有对话会自动保存，您可以随时通过 `:conversation` 回溯上下文。","某后端工程师正在紧急排查一个涉及多个微服务模块的复杂认证失败问题，需要在深夜快速定位代码逻辑漏洞并修复。\n\n### 没有 forgecode 时\n- **上下文切换频繁**：开发者需手动在 IDE、浏览器文档和终端之间反复跳转，分别查询不同文件的认证逻辑，注意力极易分散。\n- **全局理解成本高**：面对分散在鉴权中间件、数据库模型及 API 网关中的代码，人工梳理调用链路耗时费力，容易遗漏关键依赖。\n- **修复试错周期长**：提出假设后需手动编写测试用例验证，若方向错误则需回滚代码重新分析，严重拖慢排障进度。\n- **多模型对比困难**：难以同时利用 Claude 的逻辑推理与 Deepseek 的代码生成优势，只能单一依赖某个在线聊天窗口，效率受限。\n\n### 使用 forgecode 后\n- **终端内一站式闭环**：直接在终端通过 `:` 前缀命令唤起 forgecode，它自动读取工作区文件，无需离开命令行即可完成从分析到修复的全流程。\n- **智能全库语义检索**：forgecode 利用语义搜索自动关联鉴权模块与相关配置，瞬间生成清晰的认证流程图和潜在故障点分析。\n- **自主执行与验证**：接受指令后，forgecode 直接生成修复补丁并运行本地测试命令，实时反馈结果，将“分析 - 编码 - 验证”压缩为分钟级操作。\n- **灵活切换最强模型**：根据任务阶段随时切换模型（如用 Grok 做头脑风暴，用 O Series 做严谨调试），确保每个环节都获得最佳 AI 辅助。\n\nforgecode 将原本割裂的开发工具链整合为智能代理，让开发者在终端内即可实现“思考即执行”的高效研发体验。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftailcallhq_forgecode_d57b7d2d.png","tailcallhq","Tailcall","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ftailcallhq_4197bd4a.png","Next generation of API Orchestration",null,"https:\u002F\u002Ftailcall.run","https:\u002F\u002Fgithub.com\u002Ftailcallhq",[81,85,89,93,97,101,105],{"name":82,"color":83,"percentage":84},"Rust","#dea584",93.5,{"name":86,"color":87,"percentage":88},"Shell","#89e051",4,{"name":90,"color":91,"percentage":92},"HTML","#e34c26",1.1,{"name":94,"color":95,"percentage":96},"TypeScript","#3178c6",0.8,{"name":98,"color":99,"percentage":100},"JavaScript","#f1e05a",0.3,{"name":102,"color":103,"percentage":104},"CSS","#663399",0.1,{"name":106,"color":107,"percentage":104},"Nix","#7e7eff",6547,1345,"2026-04-15T11:25:47","Apache-2.0","Linux, macOS","未说明",{"notes":115,"python":113,"dependencies":116},"该工具是一个终端开发环境代理，通过 curl 命令安装。主要依赖本地 shell 环境和网络连接以访问 AI 提供商（如 OpenAI, Anthropic）的 API。支持交互式 TUI 模式、单次 CLI 模式和 ZSH 插件模式。无需本地 GPU 或大型模型下载，计算任务由云端 LLM 完成。首次运行需配置 AI 提供商的 API 密钥。",[117,118,119],"curl","sh","zsh (可选，用于插件模式)",[13,35,14,52],[122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137],"ai-workflows","artifical-intelligense","claude-3-7-sonnet","command-line","multi-agent-reinforcement-learning","shell","grok","open-router","openai","qwen","claude-4","claude-4-sonnet","ai-pair-programming","llm","cli-assistant","open-source-claude-code","2026-03-27T02:49:30.150509","2026-04-16T08:19:15.426995",[141,146,151,156,161,166],{"id":142,"question_zh":143,"answer_zh":144,"source_url":145},35236,"如何获取 Forge 的 API 密钥？","目前 Forge 已全面开放免费使用。无需加入 Discord 或等待邮件，请直接前往 README 文档中的“快速开始（Quickstart）”部分，按照步骤生成免费的 API 密钥即可开始使用。","https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Fissues\u002F422",{"id":147,"question_zh":148,"answer_zh":149,"source_url":150},35237,"运行 Forge 时程序立即退出，无法选择模型怎么办？","这通常是因为环境变量中缺少 OpenAI Token 导致的。请确保在运行 `npx forgecode@latest provider` 或其他命令前，已在环境变量中正确配置了相关的 API Token。","https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Fissues\u002F1819",{"id":152,"question_zh":153,"answer_zh":154,"source_url":155},35238,"自定义 Agent 配置中的模型设置（model config）不生效吗？","该功能在 v0.115.0 版本中已修复并生效。目前的逻辑是：如果选中的 Agent 或子 Agent 在配置中定义了 `model: xxx`，LLM 将使用该特定模型；如果未定义，则回退到通过 `\u002Fmodel` 命令全局设置的模型。建议升级至最新版本并检查 OpenRouter 活动日志以确认模型调用情况。","https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Fissues\u002F1440",{"id":157,"question_zh":158,"answer_zh":159,"source_url":160},35239,"遇到 'POST https:\u002F\u002Fopenrouter.ai\u002Fapi\u002Fv1\u002Fchat\u002Fcompletions' 错误如何解决？","此问题通常是因为选择的模型不支持工具调用（tools API）。解决方法是在 Forge REPL 中输入 `\u002Fmodel` 命令，然后选择一个支持 tools API 的模型即可继续操作。该问题已在后续版本中修复。","https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Fissues\u002F1922",{"id":162,"question_zh":163,"answer_zh":164,"source_url":165},35240,"为什么 'forge workspace info' 会导致内存占用极高（如 69GB）？","这是因为 Forge 自动将当前目录识别为工作区。如果您在主目录（Home Directory）下运行且该目录包含大量代码文件，Forge 会尝试索引整个目录导致内存飙升。解决方案是避免在根目录或主目录下直接运行，或在特定的项目子目录中启动 Forge。","https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Fissues\u002F2630",{"id":167,"question_zh":168,"answer_zh":169,"source_url":170},35241,"Forge 的自动更新机制是如何工作的？能否改为每日提示一次？","Forge 已支持更灵活的更新策略。您可以配置 `forge.yaml` 文件来设定更新频率，例如设置为每日检查一次（`check_frequency: \"daily\"`）并关闭自动更新（`auto_update: false`）。这样启动时只会提示一次，用户同意后立即更新，若拒绝则当天不再询问。","https:\u002F\u002Fgithub.com\u002Ftailcallhq\u002Fforgecode\u002Fissues\u002F711",[172,177,182,187,192,197,202,207,212,217,222,227,232,237,242,247,252,257,262,267],{"id":173,"version":174,"summary_zh":175,"released_at":176},280278,"v2.11.1","## 变更\n\n## 🐛 修复缺陷\n\n- 修复(command-list)：在列表命令的精简输出中去重代理名称 @tusharmath (#3011)\n- 修复(command-list)：在普通输出中包含自定义命令，并对 API 请求进行去重 @tusharmath (#3010)\n- 修复：解决代码库中所有不安全的字符串\u002F向量索引问题 @amitksingh1490 (#3001)\n- 修复(command-parser)：为未知命令提供友好的错误提示，并使列表命令的输出保持一致 @tusharmath (#3002)\n- 测试(vscode)：使用线程安全的保护机制修复环境变量测试中的不稳定问题 @amitksingh1490 (#2997)\n- 修复(title-generation)：在句柄被丢弃时立即取消已启动的任务，而不是依赖句柄的析构函数 @tusharmath (#2996)\n\n## 🧰 维护\n\n- 杂项(deps)：将依赖 ai 更新至 v6.0.161 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#3017)\n- 杂项(deps)：将 Rust crate tokio 更新至 v1.52.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#3016)\n- 杂项(deps)：将依赖 ai 更新至 v6.0.160 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#3015)\n- 杂项(deps)：将 Rust crate posthog-rs 更新至 v0.5.1 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#3007)\n- 杂项(deps)：将 posthog-rs 的哈希值更新至 fe1bfe0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#3006)\n- 重构(shell-plugin)：将 \\_FORGE\\_TERM\\_ENABLED 重命名为 \\_FORGE\\_TERM @tusharmath (#3005)\n- 杂项(deps)：将 posthog-rs 的哈希值更新至 9a72dff @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#3004)\n- 重构(config)：用统一的 get\\_session\\_config 替代 get\\_default\\_provider\u002Fget\\_provider\\_model @tusharmath (#3000)\n","2026-04-15T09:23:40",{"id":178,"version":179,"summary_zh":180,"released_at":181},280279,"v2.11.0","## 变更\n\n## 🚀 功能\n\n- feat(repl): 使 REPL 与 ZSH shell 插件功能对齐 @tusharmath (#2984)\n- feat(provider): 将 Modal 添加为 GLM-5 的内置提供者 @chindris-mihai-alexandru (#2871)\n\n## 📝 文档\n\n- docs(skills): 优化发布说明的语气指南，更注重清晰性而非营销用语 @tusharmath (#2982)\n\n## 🐛 修复\n\n- fix(agent): 允许配置 `enabled = false` 覆盖每个代理的推理设置 @tusharmath (#2994)\n- 从 OpenAI 模式中移除不支持的格式 @Alexx999 (#2975)\n- fix(auth): 在 OAuth 交换过程中保留 Codex 的 id_token @Edition-X (#2946)\n- fix: 增加 xAI\u002FGrok API 兼容性 @golah (#2809)\n\n## 🚀 性能\n\n- perf(display): 使用 100 毫秒超时缓存终端主题检测 @tusharmath (#2992)\n- perf(sync): 将文件上传分批合并为每批一次 HTTP 请求 @tusharmath (#2985)\n\n## 🧰 维护\n\n- chore: 将 Cargo.lock 加入版本控制 @tusharmath (#2993)\n- chore(deps): 更新依赖 ai 至 v6.0.159 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2988)\n- chore(deps): 更新依赖 @ai-sdk\u002Fgoogle-vertex 至 v4.0.109 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2987)\n- chore(deps): 将 posthog-rs 的摘要更新至 1137f7d @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2983)","2026-04-14T06:46:03",{"id":183,"version":184,"summary_zh":185,"released_at":186},280280,"v2.10.0","## 变更\n\n- 测试(markdown-stream): 更新标题和列表测试的快照 @tusharmath (#2978)\n\n## 🚀 功能\n\n- 修复(executor): 当 shell 命令的 stdout 缺少换行符时，追加换行符 @tusharmath (#2979)\n- 新增(shell): 为 zsh 插件添加终端上下文捕获 @cristian-fleischer (#2836)\n- 新增(input): 自动使用 @[] 语法包裹拖放的文件路径 @tapizquent-gail (#2808)\n\n## 📝 文档\n\n- 杂项(deps): 将 mcr.microsoft.com\u002Fdevcontainers\u002Frust 的 Docker 标签更新至 v2 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2969)\n\n## 🐛 错误修复\n\n- 修复(executor): 当 shell 命令的 stdout 缺少换行符时，追加换行符 @tusharmath (#2979)\n- 修复: 将基于字节索引的字符串切片替换为字符安全的截断操作 @amitksingh1490 (#2903)\n- 修复(google): 添加全面的 Schema 消毒处理，以兼容 Gemini API @amitksingh1490 (#2908)\n- 修复: Windows 单元测试崩溃问题 @Alexx999 (#2976)\n- 修复(deps): 将依赖库 zod 更新至 v4 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2972)\n- 修复(deps): 将依赖库 typescript 更新至 v6 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2971)\n\n## 🚀 性能优化\n\n- 性能优化: 提升 forge REPL 的 readline 性能 @Alexx999 (#2912)\n\n## 🧰 维护\n\n- 杂项(deps): 将 Rust crate rustls 更新至 v0.23.38 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2977)\n- 杂项(deps): 将 Rust crate indexmap 更新至 v2.14.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2955)\n- 杂项(deps): 将 mcr.microsoft.com\u002Fdevcontainers\u002Frust 的 Docker 标签更新至 v2 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2969)\n- 杂项(deps): 将 Rust crate similar 更新至 v3.1.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2967)\n- 杂项(deps): 将依赖库 tsx 更新至 v4.21.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2954)\n- 杂项(deps): 将依赖库 pino 更新至 v10.3.1 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2951)\n- 杂项(deps): 将依赖库 p-limit 更新至 v7.3.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2950)\n- 杂项(deps): 将依赖库 strip-ansi 更新至 v7.2.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2953)\n- 杂项(deps): 将依赖库 csv-parse 更新至 v6.2.1 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2945)\n- 杂项(deps): 将依赖库 @ai-sdk\u002Fgoogle-vertex 更新至 v4.0.108 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2962)\n- 杂项(deps): 将 Rust crate rand 更新至 v0.10.1 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2958)\n- 杂项(deps): 将依赖库 @types\u002Fnode 更新至 v24.12.2 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2944)\n- 杂项(deps): 将 Rust crate toml_edit 更新至 v0.25.11 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2938)","2026-04-13T06:20:40",{"id":188,"version":189,"summary_zh":190,"released_at":191},280281,"v2.9.9","## 变更\n\n## 🐛 修复缺陷\n\n- 修复(config)：调整偏好设置顺序，优先使用旧版的 `~\u002Fforge` 路径而非 `~\u002F.forge` @tusharmath (#2952)\n- 修复(http)：在调试文件写入时添加换行符，以确保 JSONL 格式有效 @tusharmath (#2939)\n\n## 🧰 维护\n\n- 杂项(deps)：将依赖 `@types\u002Fhandlebars` 更新至 v4.1.0 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2943)\n- 杂项(deps)：将 Rust crate `clap_complete` 更新至 v4.6.1 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2949)\n- 杂项(deps)：将依赖 `@ai-sdk\u002Fgoogle-vertex` 更新至 v4.0.107 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2948)\n- 杂项(deps)：将 Rust crate `tokio` 更新至 v1.51.1 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2937)\n- 杂项(deps)：将依赖 `ai` 更新至 v6.0.158 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2942)\n- 杂项(deps)：将依赖 `pino-pretty` 更新至 v13.1.3 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2932)\n- 杂项(deps)：将依赖 `ai` 更新至 v6.0.157 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2931)\n- 杂项(deps)：将依赖 `@ai-sdk\u002Fgoogle-vertex` 更新至 v4.0.106 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2928)","2026-04-11T07:58:27",{"id":193,"version":194,"summary_zh":195,"released_at":196},280282,"v2.9.8","## 变更\n\n## 🐛 修复 bug\n\n- 修复（更新）：将过时的 antinomyhq\u002Fforge 引用替换为 tailcallhq\u002Fforgecode @EmojiPati (#2930)\n\n## 🧰 维护\n\n- 杂项（依赖）：将 posthog-rs 的摘要更新至 0e19469 @[renovate[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Frenovate) (#2927)\n","2026-04-10T15:21:37",{"id":198,"version":199,"summary_zh":200,"released_at":201},280283,"v2.9.7","## 变更\r\n\r\n## 🐛 修复 bug\r\n\r\n- 修复：优化配置路径选择逻辑 @tusharmath (#2926)\r\n","2026-04-10T10:27:55",{"id":203,"version":204,"summary_zh":205,"released_at":206},280284,"v2.9.6","## 变更\n\n## 🐛 修复缺陷\n\n- 修复(config)：防止 base_path 在 ~\u002Fforge 仍保存用户数据的情况下切换到 ~\u002F.forge @tusharmath (#2925)\n","2026-04-10T09:40:19",{"id":208,"version":209,"summary_zh":210,"released_at":211},280285,"v2.9.5","## 变更\n\n## 🐛 Bug 修复\n\n- 修复（fd）：在工作区文件索引中排除锁文件 @tusharmath (#2923)\n- 修复（zsh）：动态解析配置路径，以打开正确的文件进行编辑 @tusharmath (#2919)\n- 修复：减少对 sage 代理在 sem_search 中的过度依赖 @amitksingh1490 (#2913)\n","2026-04-10T04:47:51",{"id":213,"version":214,"summary_zh":215,"released_at":216},280286,"v2.9.4","## 变更\n\n## 🐛 Bug 修复\n\n- 修复(openai): 处理提供者同时发出 reasoning 和 reasoning_content 字段的问题 @tusharmath (#2911)\n","2026-04-10T01:49:14",{"id":218,"version":219,"summary_zh":220,"released_at":221},280287,"v2.9.3","## 变更\n\n## 🐛 修复缺陷\n\n- 修复(openai): 处理提供商同时发出 reasoning 和 reasoning_content 字段的问题 @tusharmath (#2911)\n- 修复(cli): 在设置会话模型之前显示智能体列表 @tusharmath (#2910)\n\n## 🧰 维护\n\n- 重构(config): 将默认的主目录从 ~\u002Fforge 更改为 ~\u002F.forge @youming-ai (#2902)\n","2026-04-09T15:34:02",{"id":223,"version":224,"summary_zh":225,"released_at":226},280288,"v2.9.2","## Changes\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix(title-generation): abort background task on conversation end @amitksingh1490 (#2906)\r\n\r\n## 🧰 Maintenance\r\n\r\n- chore(config): add 524 to retryable status codes @tusharmath (#2895)\r\n","2026-04-09T11:59:20",{"id":228,"version":229,"summary_zh":230,"released_at":231},280289,"v2.9.1","## Changes\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix(cli): add missing config-model command alias @ssddOnTop (#2901)\r\n- fix: route OpenCode Go requests to correct endpoint instead of Zen @amitksingh1490 (#2899)\r\n","2026-04-09T06:59:44",{"id":233,"version":234,"summary_zh":235,"released_at":236},280290,"v2.9.0","## Changes\r\n\r\n## 🚀 Features\r\n\r\n- feat(skill): add agents skills from ~\u002F.agents\u002Fskills @tusharmath (#2890)\r\n- feat(orch): enforce pending todo completion before task finish @amitksingh1490 (#2841)\r\n- feat(config): add currency symbol and conversion rate to rprompt @tusharmath (#2887)\r\n- feat(ui): replace :env and :config table with full TOML config view @tusharmath (#2886)\r\n- feat(mcp): Add OAuth 2.0 authentication support for MCP servers @amitksingh1490 (#2842)\r\n- feat: Add OpenCode Go provider support @ravshansbox (#2825)\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix(cli): set provider and model atomically @tusharmath (#2885)\r\n- fix(config): parse selected fields safely when names contain spaces @amitksingh1490 (#2883)\r\n\r\n## 🧰 Maintenance\r\n\r\n- chore(provider): add new model entries to provider catalogs @amitksingh1490 (#2897)\r\n- chore(deps): bump the minor group across 1 directory with 2 updates @[dependabot[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Fdependabot) (#2856)\r\n","2026-04-09T05:14:47",{"id":238,"version":239,"summary_zh":240,"released_at":241},280291,"v2.8.0","## Changes\r\n\r\n## 🚀 Features\r\n\r\n- feat: subagent as task @amitksingh1490 (#2508)\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix(config): re-read ForgeConfig via infra get\\_config @tusharmath (#2878)\r\n- fix(http): consolidate sanitize\\_headers into forge\\_infra and expand sensitive header list @amitksingh1490 (#2879)\r\n\r\n## 🧰 Maintenance\r\n\r\n- fix(config): re-read ForgeConfig via infra get\\_config @tusharmath (#2878)\r\n- chore(skill): add resolve-fixme skill to find and triage FIXME @tusharmath (#2876)\r\n","2026-04-07T11:45:45",{"id":243,"version":244,"summary_zh":245,"released_at":246},280292,"v2.7.0","## Changes\r\n\r\n## 🚀 Features\r\n\r\n- feat(tools): add multi\\_patch tool for batch file edits @amitksingh1490 (#2840)\r\n- feat(config): allow configuration of the base\\_path @tusharmath (#2864)\r\n\r\n## 📝 Documentation\r\n\r\n- docs(README): add newcomer orientation, ZSH plugin reference, and sync CLI docs @ahundt (#2862)\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- feat(tools): add multi\\_patch tool for batch file edits @amitksingh1490 (#2840)\r\n- fix(http): append debug request body chunks instead of overwriting @tusharmath (#2875)\r\n- fix(ui): allow model selection when provider activation completes without selection @amitksingh1490 (#2863)\r\n- fix(app): return error when conversation is not found @tusharmath (#2852)\r\n- fix: atomic provider and model selection with proper cancellation handling  @ashprakasan (#2803)\r\n- fix: correct token double-counting for Anthropic and Bedrock providers @amitksingh1490 (#2861)\r\n- fix(sync): exclude symlinked files from discovery results @tusharmath (#2849)\r\n- fix(bedrock): sanitize tool call IDs for Anthropic compatibility @amitksingh1490 (#2837)\r\n\r\n## 🧰 Maintenance\r\n\r\n- chore(auth): add warning for Claude Code provider about account ban risk @amitksingh1490 (#2838)\r\n- chore(alias): add 'provider' alias for provider-login commandchore @amitksingh1490 (#2865)\r\n- refactor(config): read ForgeConfig once at startup and thread it through the stack @tusharmath (#2850)\r\n- chore(deps): bump the major group across 1 directory with 5 updates @[dependabot[bot]](https:\u002F\u002Fgithub.com\u002Fapps\u002Fdependabot) (#2783)\r\n","2026-04-07T05:25:11",{"id":248,"version":249,"summary_zh":250,"released_at":251},280293,"v2.6.0","## Changes\r\n\r\n## 🚀 Features\r\n\r\n- feat(auth): add OAuth authorization code + PKCE for Codex provider @tivris (#2790)\r\n- feat(ui): add workspace init confirmation before syncing @tusharmath (#2822)\r\n- feat(config): add `[[providers]]` in `.forge.toml` @tusharmath (#2821)\r\n- feat(app): make commit history depth configurable via max\\_commit\\_count @tusharmath (#2762)\r\n- feat(config): add config-reload to clear all session overrides @tusharmath (#2819)\r\n\r\n## 🧰 Maintenance\r\n\r\n- chore(provider): add Google AI Studio support @tivris (#2805)\r\n","2026-04-04T03:23:42",{"id":253,"version":254,"summary_zh":255,"released_at":256},280294,"v2.5.2","## Changes\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix: add GitHub Copilot optimization headers for billing. @amitksingh1490 (#2813)\r\n- fix: normalize stringified tool call arguments on resume @amitksingh1490 (#2814)\r\n","2026-04-03T07:03:18",{"id":258,"version":259,"summary_zh":260,"released_at":261},280295,"v2.5.1","## Changes\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- Revert \"fix(zsh): use global scope for typeset to support lazy loading\" @ssddOnTop (#2810)\r\n","2026-04-02T22:46:19",{"id":263,"version":264,"summary_zh":265,"released_at":266},280296,"v2.5.0","## Changes\r\n\r\n- Force .zsh to be checked out with LF line endings @Alexx999 (#2800)\r\n\r\n## 🚀 Features\r\n\r\n- feat(reasoning): add reasoning-effort config settings @tusharmath (#2775)\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix(zsh): use global scope for typeset to support lazy loading @losinggeneration (#2776)\r\n- fix(walker): respect nested .gitignore files even if it's not git repo @laststylebender14 (#2785)\r\n- fix(windows): enable VT processing on stdout handle for ANSI rendering @stier1ba (#2788)\r\n- perf(workspace): improve workspace sync performance @tusharmath (#2787)\r\n- fix(select): replace unsafe transmute\\_copy with safe Any downcasting in confirm prompt @tusharmath (#2794)\r\n\r\n## 🚀 Performance\r\n\r\n- perf(workspace): improve workspace sync performance @tusharmath (#2787)\r\n\r\n## 🧰 Maintenance\r\n\r\n- chore(skill): add a skill to resolve PR comments @tusharmath (#2793)\r\n","2026-04-02T17:36:54",{"id":268,"version":269,"summary_zh":270,"released_at":271},280297,"v2.4.1","## Changes\r\n\r\n## 📝 Documentation\r\n\r\n- fix: zsh doctor on windows @ssddOnTop (#2433)\r\n\r\n## 🐛 Bug Fixes\r\n\r\n- fix(context): prevent duplicate reasoning block @ssddOnTop (#2782)\r\n- fix: zsh doctor on windows @ssddOnTop (#2433)\r\n- fix(ui): initialize state selectively to prevent background task conflicts @tusharmath (#2773)\r\n- fix(operation): report actual file total\\_lines instead of content slice line count @tusharmath (#2771)\r\n- fix(git\\_app): add retry mechanism for commit message generation @tusharmath (#2772)\r\n- Revert \"fix(zsh): use global scope for typeset to support lazy loading\" @tusharmath (#2770)\r\n- fix(zsh): use global scope for typeset to support lazy loading @losinggeneration (#2769)\r\n\r\n## 🧰 Maintenance\r\n\r\n- refactor(env): drop configuration fields from env and update usage @tusharmath (#2755)\r\n","2026-04-02T04:43:32"]