Formax：开源AI工程助手，终端与GUI双模式助力开发

1. 项目概述：一个终端优先的AI工程助手

如果你和我一样，日常大部分时间都泡在终端里，那么一个能直接在命令行里和你对话、帮你写代码、分析项目的AI助手，吸引力无疑是巨大的。Formax 就是这样一个项目，它将自己定位为一个“终端优先”的AI助手，专为软件工程任务而生。它的设计灵感直接来源于 Claude Code，你可以把它理解为一个开源、可自部署的“平替”版本，目标是让你在本地开发环境中，也能获得类似 Claude Code 那种流畅的代码生成、分析和重构体验。

这个项目最吸引我的地方在于它的“终端原生”特性。它不是一个简单的聊天机器人包装，而是深度集成了TUI（终端用户界面）和GUI（图形用户界面）两种工作流。这意味着，无论你是习惯在 iTerm2 或 Alacritty 里敲命令的硬核开发者，还是更喜欢在图形界面里拖拽点击，Formax 都提供了相应的入口。它的核心是作为一个智能代理（Agent），能够理解你的项目上下文，执行诸如代码审查、生成测试、解释复杂逻辑、甚至规划开发任务（Plan Mode）等一系列工程活动。

目前项目还处于 Beta 阶段，官方也坦诚地表示它更适合学习、实验和架构研究，而非追求绝对稳定的生产级日常使用。但这恰恰是开源项目的魅力所在——你可以深入其内部，看看一个现代化的AI工程助手是如何被构建起来的，从工具调用、上下文管理到多模态交互，这里面的设计思路和实现细节，对于想自己动手构建AI应用或研究Agent系统的开发者来说，本身就是一份极佳的参考资料。

2. 核心架构与设计思路拆解

2.1 灵感来源与实现路径

Formax 明确声明其灵感来源于 Claude Code v2.0.67，但并非其官方分支或复刻。这是一个非常重要的定位。这意味着开发者 Yusifeng 是通过观察、逆向工程（例如分析网络请求痕迹）和合理推测来重新实现类似的功能和行为，而不是直接使用上游的源代码。这种“重新发明轮子”的做法，在开源社区里往往能诞生出更具灵活性、更适应特定需求（比如本地化部署、定制化工作流）的项目。

这种实现路径带来了几个关键特点：

1. 行为模仿而非代码复制：Formax 追求的是在用户体验和功能效果上接近 Claude Code，但在底层实现上拥有完全的自主权。这允许它采用不同的技术栈（如 Node.js + React + Ink），并做出更适合开源社区和开发者自托管的技术选型。
2. 明确的功能边界：项目文档坦率地列出了当前的“差距”（Gaps），比如 Claude Code Hooks 支持不完整、工具执行行为不完全一致、MCP（Model Context Protocol）暂不支持等。这种透明度有助于设定合理的用户预期，也指明了项目未来的发展方向。
3. AI驱动的开发过程：一个非常有趣的细节是，项目维护者提到这个项目是“100%使用 Codex 构建的”。这意味着开发过程本身就是一个AI辅助开发的绝佳案例。仓库里保留的.codex/skills、docs/和plans/等目录，正是AI参与构思、规划和实现所留下的“痕迹”，对于研究AI如何辅助复杂软件开发具有很高的参考价值。

2.2 技术栈选型解析

Formax 的技术栈选择清晰地反映了其“全栈JavaScript/TypeScript”和“多端交付”的目标。

• 运行时与包管理：基于 Node.js（要求版本 >=20），使用 npm 进行包管理和分发。这使得它能够无缝融入现代前端和Node.js后端开发者的工具链，也便于通过npm install -g进行全局安装。
• 终端界面（TUI）：使用 Ink 库来构建命令行中的交互式界面。Ink 允许开发者使用 React 组件的方式来构建TUI，这大大降低了开发复杂命令行应用的难度，并能保持与Web开发一致的心智模型。Formax 的TUI需要处理复杂的对话流、代码高亮、列表选择等交互，Ink 是一个合理的选择。
• 图形界面（GUI）：GUI部分基于 React 构建，并通过 Electron 打包为桌面客户端。formax web命令启动的是一个本地Web服务器，而formax app-server则提供了一个 JSON-RPC 后端，供更深入的 IDE 集成或第三方客户端调用。这种设计将核心逻辑（Agent引擎、API调用、项目管理）与界面层分离，具备了良好的可扩展性。
• AI 集成：支持 Anthropic（Claude系列模型）和 OpenAI 兼容的API（如 GPT-4, o1等）。配置界面也预留了 Gemini 的支持，尽管运行时尚未完全实现。这种多模型支持的设计，让用户可以根据成本、效果和速度自由选择后端。

注意：选择 Ink 和 React 这一套技术栈，意味着项目对现代前端生态有较强的依赖。对于不熟悉 React 的开发者来说，想要深度定制UI或修复前端bug可能会有一定的学习成本。不过，这也使得拥有前端经验的贡献者更容易上手。

2.3 核心工作流：TUI vs. GUI

Formax 提供了两种主要的工作流，适应不同的使用场景和开发者偏好。

TUI（终端用户界面）工作流： 这是 Formax 的“终端优先”理念的核心体现。通过在项目根目录直接运行formax命令，你会在终端内启动一个全屏的、交互式的聊天界面。在这里，你可以：

• 与AI助手进行自然语言对话，讨论当前项目的代码。
• 使用/命令触发特定功能，例如/init来为项目生成一个CLAUDE.md文件（类似于项目的AI说明书）。
• 进入“规划模式”（Plan Mode），让AI帮你拆解一个复杂的开发任务，形成可执行的步骤列表。
• 执行代码审查、运行测试、调用系统命令（在确认后）等。

TUI模式的优点是极致的高效和沉浸感，无需离开终端，上下文切换成本极低。特别适合快速迭代、调试和执行一些自动化脚本任务。

GUI（图形用户界面）工作流： 通过formax web命令启动一个本地Web应用，或者在桌面端使用 Electron 打包的客户端。GUI 提供了更丰富的视觉交互：

• 更直观的对话线程管理。
• 更好的代码块渲染和文件树导航。
• 桌面客户端支持原生的文件夹选择器。
• 界面设计上故意向 Codex 看齐，追求简洁和开发者友好。

GUI模式更适合需要长时间、多线程对话的复杂任务，或者当你需要同时参考多个文件、对比不同代码版本时。图形界面在信息呈现的密度和友好度上通常更有优势。

两种模式共享同一个后端配置和项目上下文，你可以根据手头任务灵活切换。例如，在终端里快速生成一个函数，然后在GUI里进行详细的结构审查。

3. 安装、配置与快速上手

3.1 环境准备与安装

Formax 的安装过程非常标准，前提是你的系统已经安装了符合要求的 Node.js 环境。

1. 检查 Node.js 版本： 打开你的终端，运行以下命令。Formax 要求 Node.js 版本不低于 20。

   node --version

   如果版本低于 20，你需要先升级 Node.js。推荐使用 nvm （macOS/Linux）或 nvm-windows 来管理多个Node版本，这样可以灵活切换而不影响系统其他项目。

   # 使用 nvm 安装并切换到 Node.js 20+ nvm install 20 nvm use 20

2. 全局安装 Formax： 由于 Formax 是一个命令行工具，我们通常进行全局安装，以便在任何目录下都能使用formax命令。注意，当前稳定版本是 Beta。

   npm install -g @yusifeng/formax@beta

   安装完成后，可以通过以下命令验证是否安装成功：

   formax --version

   或者查看帮助信息：

   formax --help

3.2 首次运行与向导式配置

安装完成后，不要急于直接使用。Formax 的核心能力依赖于大模型API，因此第一步是进行配置。

方法一：直接启动，按需配置这是最快捷的方式。进入你想要让AI助手协助的项目目录：

cd /path/to/your/javascript-project formax

如果是第一次在该机器上运行，Formax 会检测到缺少必要的凭证（如API Key）和运行时配置。TUI界面会引导你完成一个简单的设置流程，通常会让你输入：

• AI 服务提供商：选择 Anthropic 或 OpenAI。
• API Key：输入对应平台的API密钥。请务必妥善保管你的API Key，Formax 会将其加密后存储在本地配置文件~/.formax/config.json中。
• 默认模型：选择你想使用的模型，例如claude-3-5-sonnet-latest或gpt-4o。
• 项目根目录确认：确认当前目录是否是你想要AI操作的根目录。

这个过程是交互式的，跟着提示一步步走即可。

方法二：运行独立设置命令如果你希望先完成所有配置，再开始使用，可以运行专门的设置命令：

formax setup

这个命令会启动一个配置向导，引导你设置所有必要的参数，包括上述的API信息，以及一些可选配置，如网络代理、默认编辑器等。完成设置后，再运行formax就会直接进入主界面。

实操心得：我强烈推荐先使用formax setup进行完整配置。因为在直接运行formax时弹出的配置流程可能比较精简，而setup命令提供的选项更全面。特别是如果你身处需要配置网络代理的环境，或者想预先设置好多个不同用途的模型配置档，独立设置命令是更好的选择。

3.3 配置文件解析

所有配置都存储在~/.formax/目录下（在Windows上是C:\Users\<你的用户名>\.formax\）。了解这个目录的结构有助于高级调试和配置管理。

• config.json: 核心配置文件，包含API密钥（加密存储）、默认模型、端点URL等。
• logs/: 运行日志目录，如果遇到问题，查看这里的日志是首要的排查步骤。
• cache/: 项目上下文缓存，用于加速AI对大型代码库的理解。

一个典型的config.json可能长这样：

{ "providers": { "anthropic": { "apiKey": "encrypted:xxxx...", // 加密后的密钥 "defaultModel": "claude-3-5-sonnet-latest" }, "openai": { "apiKey": "encrypted:yyyy...", "defaultModel": "gpt-4o", "baseURL": "https://api.openai.com/v1" // 可指向自定义或第三方兼容端点 } }, "defaultProvider": "anthropic", "editor": "code", // 默认用VSCode打开文件 "enableTelemetry": false // 是否允许匿名数据收集 }

修改配置的注意事项：

1. 不要手动编辑加密的apiKey字段。如果你想更换API Key，请再次运行formax setup重新输入。
2. 你可以手动修改defaultModel、baseURL等非敏感字段。
3. 如果你想完全重置配置，可以删除整个~/.formax目录，然后重新运行设置。

4. 核心功能深度体验与实操

4.1 基础对话与上下文管理

启动 Formax 后，你就进入了一个与AI助手对话的环境。它的核心是理解你当前所在的项目。

• 项目上下文自动加载：Formax 会自动读取当前目录下的文件结构，并将其作为对话的“背景知识”。当你问“这个index.js文件是做什么的？”时，它不需要你上传文件，因为它已经在上下文中了。
• 智能文件感知：你可以通过@符号来引用特定文件。例如，输入“请解释一下@src/utils/helper.ts中的formatDate函数”，AI会精准定位并分析该文件中的特定函数。
• 对话历史与线程：在GUI模式下，对话以“线程”的形式管理，类似于Slack或Discord。你可以为不同的功能模块或bug创建不同的对话线程，保持上下文隔离。TUI模式同样会维护本次会话的历史。

实操示例：快速理解一个陌生项目假设你刚接手一个Node.js项目，想快速了解其入口和主要结构。

1. cd到该项目根目录。
2. 运行formax。
3. 在聊天框中输入：“这是一个什么项目？它的主要入口文件是哪个？依赖了哪些核心外部库？”
4. AI助手会扫描package.json、主目录文件，并给出总结。你可以继续追问：“那么，启动这个项目的命令是什么？”、“src/models目录下的文件是做什么的？”

这种方式比手动翻阅文档或代码要高效得多，尤其适合进行项目交接或快速审计。

4.2 特色功能：规划模式与/init命令

规划模式： 这是模仿 Claude Code 的一个强大功能。当你面对一个相对复杂、多步骤的任务时，可以激活规划模式。例如，你想“为项目添加用户登录功能”。

1. 在聊天输入框里输入/plan或者点击相关按钮（GUI中）进入规划模式。
2. 描述你的任务：“添加基于JWT的用户登录功能，包括注册、登录API，以及一个简单的用户模型。”
3. AI 会生成一个详细的、分步骤的计划。这个计划可能包括：
   • 步骤1：创建User模型定义文件（Mongoose Schema 或 Prisma Model）。
   • 步骤2：创建auth.controller.js和对应的路由。
   • 步骤3：实现密码哈希（使用bcrypt）和JWT生成/验证工具函数。
   • 步骤4：编写单元测试。
   • 步骤5：更新API文档。
4. 你可以让AI按步骤执行，也可以自己选择性地执行其中几步。AI会在每个步骤中生成具体的代码，并询问你是否应用更改。

规划模式将AI从一个代码片段的生成器，提升为了一个项目级的“初级架构师”或“项目管家”，能帮你理清思路，拆解任务。

/init命令： 这个命令用于生成项目的CLAUDE.md文件。这个文件是什么？你可以把它理解为写给AI看的“项目说明书”。当AI助手（无论是Formax还是未来的其他工具）介入你的项目时，这个文件能提供至关重要的上下文：项目目的、技术栈、代码规范、如何运行、测试、部署等。

运行/init后，AI会分析你的项目，并生成一个初步的CLAUDE.md草案，然后与你交互式地完善它。一个写好的CLAUDE.md能极大提升后续所有AI辅助任务的准确度和效率。

4.3 代码审查与子代理协作

代码审查： 你可以将一段代码（通过粘贴或@引用文件）交给AI进行审查。例如：“请审查下面这段React Hook的代码，看看是否有性能问题或潜在bug。” AI会从代码风格、最佳实践、潜在错误（如无限循环、内存泄漏）、安全性等多个角度给出反馈。这相当于一个随时待命的资深代码审查员。

子代理： 这是一个更高级的概念。在某些复杂任务中，Formax 可以创建“子代理”来专门处理某个子问题。例如，主代理负责整体登录功能规划，它可能会创建一个子代理专门去研究“在当前框架下实现JWT的最佳实践”，然后将研究结果汇报给主代理，整合进最终方案。这模拟了人类团队中专家协作的模式，目前该功能在演示中可见，是项目正在积极探索的方向。

4.4 GUI 模式详解与高级部署

运行formax web后，默认会在浏览器打开http://localhost:3000（具体端口可能根据配置变化）。这个Web界面提供了更丰富的交互。

• 线程管理：左侧是所有的对话线程，可以创建、归档、删除。顶部始终有一个“Add project”按钮。
• 桌面端 vs 纯浏览器：
  • 在通过formax web启动的Electron桌面客户端中，“Add project”按钮会调用操作系统的原生文件夹选择器，选择后即在该项目根目录下开启一个新对话线程。
  • 如果直接在浏览器中访问本地服务，由于浏览器安全限制，无法直接访问本地文件系统。此时“Add project”按钮会显示“Desktop only”提示。这意味着纯浏览器模式更适合进行基于已有上下文的对话，而不适合初始化新项目。
• 代码渲染：GUI中对代码块的渲染（语法高亮、折叠、复制）体验远优于TUI。

高级部署模式： Formax 提供了更解耦的部署选项，适合集成到自定义工作流或IDE中。

• formax app-server：启动一个JSON-RPC 后端服务。这个服务暴露了一套标准的接口，任何GUI客户端（比如你想自己写一个VS Code插件）或IDE都可以通过JSON-RPC协议与之通信，调用Formax的核心能力。这为深度集成打开了大门。
• formax serve：启动一个更底层的WebSocket 桥接服务。这通常用于高级调试，或者当你希望将Formax的AI引擎部署在一台服务器上，而多个轻量级客户端通过网络连接它时的场景。

5. 常见问题、排查技巧与局限性

5.1 安装与启动问题

5.2 API 与网络问题

5.3 功能与行为异常

5.4 当前已知局限性

正如项目文档明确指出的，Formax 仍处于Beta阶段，存在一些与 Claude Code 的差距和自身限制，使用时需心中有数：

1. Claude Code Hooks 支持不完整：Claude Code 可能有一些深度的IDE集成钩子，Formax 尚未完全实现。
2. 工具执行行为差异：WebFetch（网络抓取）和WebSearch（网络搜索）这类工具的稳定性和行为可能与原版不完全一致。MCP（Model Context Protocol）暂不支持，这意味着一些通过MCP协议接入的第三方工具（如数据库连接器、特定云服务CLI）目前无法使用。
3. GUI 功能相对基础：目前的Web界面比较简约，一些更高级的UI交互（如复杂的代码差异对比可视化）可能还在开发中。
4. 稳定性与性能：作为Beta软件，偶尔可能会遇到崩溃、内存泄漏或响应迟缓的情况。复杂的任务处理可能不如原版稳定。

安全警告：Formax 是一个强大的工具，但它执行的文件修改、系统命令都基于AI的理解。务必养成习惯，仔细审查AI建议的每一处代码更改和每一个命令，特别是涉及删除文件、安装包、修改系统配置等危险操作时。永远不要盲目点击“全部接受”。在关键项目中操作前，最好在独立的分支或副本中进行。

6. 进阶使用与定制化探索

6.1 提升效率的提示词技巧

与任何AI助手合作，清晰的沟通是关键。以下是一些针对Formax/软件工程场景的提示词技巧：

• 提供充足上下文：在提问前，用一两句话说明背景。例如：“我正在开发一个React Native的购物车组件，当前代码是...，我现在遇到的问题是状态更新后UI不刷新。”
• 明确任务边界：指定你希望AI做什么，不做什么。例如：“请只修改handleCheckout函数，不要动其他部分的样式。”
• 指定输出格式：如果你需要特定格式的代码或回答，直接说明。例如：“请用TypeScript接口定义这个用户对象，并加上JSDoc注释。” 或者 “请用Markdown表格列出这个函数的参数说明。”
• 分步引导：对于复杂任务，可以模仿规划模式，自己先拆解。例如：“第一步，请分析这个错误堆栈，定位可能出问题的文件。第二步，针对那个文件，给出修复建议。”
• 利用项目知识：多使用@引用文件，让AI的答案基于你的实际代码，而不是泛泛而谈。

6.2 项目结构与开发贡献

如果你对Formax本身感兴趣，想学习其架构或参与贡献，克隆其仓库是最好的方式。

git clone https://github.com/yusifeng/formax.git cd formax npm install npm run dev # 通常这会启动开发模式

项目仓库里几个关键部分：

• src/: 核心源代码目录。
• docs/: 项目文档。
• CODEMAP.md: 代码地图，是理解项目模块划分的绝佳起点。
• .codex/skills,plans/: 如前所述，这是AI辅助开发留下的“遗迹”，对于研究AI如何规划编码任务非常有启发性。

维护者鼓励通过PR来贡献代码或提出功能建议。由于项目明确追求与Claude Code的兼容性，因此与Claude Code行为相关的研究和实现可能会被优先考虑。

6.3 与现有工作流集成

虽然Formax本身是一个独立应用，但你可以通过一些方式将其融入现有工作流：

• 作为代码审查伙伴：在完成一个功能模块后，不用立即发起人工CR，先让Formax快速过一遍，检查明显的逻辑错误、代码风格问题和潜在bug。
• 作为学习工具：在阅读开源项目源码时，打开该项目目录，用Formax来提问，让它帮你解释模块关系、函数作用，比单纯看代码更高效。
• 作为文档生成器：利用其对话能力，让它为你的函数、类生成初步的JSDoc或Markdown文档草稿。
• 与IDE共存：你可以一边在VS Code里写代码，一边在旁边的终端或浏览器窗口开着Formax，随时提问。未来如果formax app-server的JSON-RPC接口稳定，社区可能会出现直接的IDE插件。

Formax 代表了一种趋势：AI助手正从通用的聊天机器人，进化为深度集成在开发者环境中的专业副驾。它可能还不完美，但作为一个开源项目，它为我们提供了一个可窥视、可参与、可定制的未来开发体验样本。无论是想提升日常效率，还是对AI Agent的实现原理感到好奇，Formax 都值得你花时间安装、把玩一番。记住，从简单的代码解释开始，逐步尝试更复杂的规划和重构任务，并始终保持“审查”的习惯，你就能安全、有效地驾驭这个强大的工具。