formax
yusifeng/formax加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
凌晨两点，你正在赶一个紧急功能，突然发现某个 API 的参数记不清了。以往的流程是：切窗口、打开浏览器、搜索文档、改回编辑器——打断节奏不说，回来往往要花几秒重新找回上下文。
如果你的终端里就住着一个懂你代码库的 AI 助手，可以直接帮你查文档、写代码、改 bug、跑测试呢？
Formax 就是这样一个项目。它是一个开源的 Claude Code 风格 AI 编程助手，核心理念是"终端优先"（Terminal-first），同时提供 GUI 网页界面，让开发者能在自己最习惯的工作流里调用 AI 能力。
图1：Formax 在终端中的主界面演示
Formax 的诞生源于一个很朴素的想法：Claude Code 这款工具体验极佳，但它是闭源的，用户既无法深入了解其实现细节，也无法根据自己的需求进行定制。
作者 yusifeng 通过观察网络流量等手段，逐步逆向实现了 Claude Code 的核心交互模式，并将整个系统以 MIT 协议开源。项目名称 Formax 取自 "For Maximum"——追求最大化的开发效率。
需要明确的是，Formax 是一个独立项目，与 Anthropic 公司无任何官方关联，代码完全自主编写，只是行为参考了 Claude Code v2.0.67 的交互模式。项目当前处于 Beta 阶段，更适合用于学习、实验和架构研究，而非作为生产环境的日常主力工具。
Formax 最有价值的设计哲学，不是"做了一个 TUI 工具"或"做了一个 Web 工具"，而是提出了一个优雅的多端一致性模型：同一语义核心，三种渲染入口。
核心在 packages/semantics/src/index.ts 中定义 canonical event（规范事件），这是所有渲染端共享的真值来源。TUI、Web、app-server 三端的 transcript（对话记录）都必须向这套语义模型收敛，而不是各自发明状态机。
| 入口模式 | 命令 | 说明 |
|---|---|---|
| CLI/TUI | formax | 基于 Ink 库渲染的终端界面，支持全键盘操作 |
| Web GUI | formax web | React + TypeScript 构建的网页客户端 |
| app-server | formax app-server | JSON-RPC over stdio，可被 IDE 集成 |
这种设计的好处在于：当你在 TUI 里用 formax 写了一半的代码，切到浏览器里 formax web 能无缝接着干，因为两端的语义状态来自同一个核心。
图2：计划模式（Plan mode）演示——AI 先规划再执行
项目采用 npm workspaces 管理 Monorepo，共 5 个包：
Formax 引入了计划模式，要求 AI 在执行前先提出行动方案，经用户确认后再执行。这对生产环境尤为重要——避免 AI 在不明确意图时做出不可逆的修改（如大范围删除文件）。
支持将复杂任务分解为多个子代理并行处理，并在代码提交前进行结构化审查。演示动画展示了子代理协同完成跨模块重构的场景。
图3：子代理与代码审查功能演示
通过 /init 命令在项目根目录生成 CLAUDE.md 文件，作为 AI 的上下文说明文档。这个文件记录了项目的架构决策、业务规则和特殊约定，让 AI 在整个会话周期内保持一致的上下文理解。
内置 WebFetch 和 WebSearch 工具，使 AI 能够实时查阅在线文档和最新技术资料。不过项目文档明确标注，这两个工具目前存在"已知稳定性与行为差异"。
从 package.json 可以看到完整的依赖图谱：
.ts / .tsx 文件）项目还内置了大量自验证脚本，如 check-layer-coverage、check-presenter-parity、check-pack-safety 等，体现了极高的工程自驱力。
CI 流水线包含 codecov 覆盖率追踪，当前覆盖率有 badge 展示。文档方面有 AGENTS.md（代理指令）、CODEMAP.md（代码导航）、ARCHITECTURE.md（架构说明）三层治理文档体系。
安装方式非常简洁，一行 npm 命令即可：
npm i -g @yusifeng/formax@beta
要求 Node.js >= 20 环境，满足条件后基本可以立即使用。
首次运行会提示配置 API 密钥（Claude API Key）。如果想走完整配置向导：
formax setup
配置文件默认保存在 ~/.formax/ 目录。
不需要 Terminal 环境？直接启动 Web UI：
formax web
Web 端支持线程管理、上下文切换，体验接近 Claude Code 网页版。桌面 Electron 客户端额外支持系统原生文件夹选择器。
需要指出的是，项目未提供 Dockerfile 或 docker-compose.yml，这意味着：
项目 README 坦诚地列出了当前的功能差距：
这些坦诚的声明反而体现了项目的工程成熟度——知道自己做到了什么，没做到什么。
| 维度 | 评价 |
|---|---|
| 架构设计 | ★★★★★ — 语义核心模型优雅，扩展性强 |
| 代码规范 | ★★★★☆ — 大量自定义检查脚本，CI 完善 |
| 测试覆盖 | ★★★★☆ — 有 codecov badge，具体数据待查 |
| 文档质量 | ★★★★★ — 架构文档 + 代码导航 + 治理文档三层体系 |
| TypeScript 覆盖率 | 高（monorepo 全量 TS） |
Formax 不仅仅是一个 Claude Code 替代品，更重要的是它提供了一个可学习的 AI 编程助手实现范本：
对于 AI 编程助手赛道的开发者而言，Formax 的架构文档（ARCHITECTURE.md）本身就是一份优秀的技术学习材料。
| 维度 | 结论 |
|---|---|
| 适合人群 | AI 编程助手研究者、TypeScript 开发者、CLI 工具爱好者 |
| 上手难度 | 低（npm 安装即用），但需配置 Claude API |
| 生产可用性 | Beta，不建议作为主力生产工具 |
| 容器化部署 | 不支持 |
| Web UI | 支持 |
| 深度学习价值 | 高（架构设计值得研究） |
如果你对 Claude Code 的内部工作原理感兴趣，或想在本地搭建一个可定制的 AI 编程助手环境，Formax 是一个值得研究的目标。对于只是想用 AI 辅助编程的用户，官方 Claude Code 或 Cursor 等成熟工具仍是更稳妥的选择。