使用说明

菲茨锻造厂

本地LLM的代理编码规划工具。

规划工件 • 为什么 fitz-forge? • 管道 • 评估 • 文档 • GitHub

Task: "Add WebSocket support to the chat API"
(Given a real codebase with FastAPI routes, Pydantic schemas, and an existing REST chat endpoint.)

❌ Raw local LLM

"Add a WebSocket endpoint.
 Use the websockets library.
 Create handlers.
 Add auth middleware."

🔨 fitz-forge

Phase 1: Extend api/routes/chat.py - Reuse existing ChatService - Validate token with current auth layer - Test: pytest tests/api/test_chat_ws.py

第二阶段：调整模式/chat.py

保留当前聊天消息形状
验证：pydantic模型验证（）

→ fitz-forge 将广泛的编码请求转化为基础上下文、经过审查的决策、工件代码和验证路线图。

从何开始🚀

[！重要] fitz-forge plan 默认情况下首先运行本地。局部模型负责规划工作，fitz-sage负责代码检索， SQLite存储作业和检查点，可选的API检查仅在您配置时运行。

pip install fitz-forge

fitz-forge prep
fitz-forge plan "Add WebSocket support to the chat API"

结果是一个规划工件：存储库上下文、实现状态、架构决策、拟议代码人工或编码代理可以使用工件、审查结果和命令来验证工作。

关于

fitz-forge 是用于代理编码规划的LLM工具。它读取真实的存储库，收集相关上下文，分解所请求的更改，生成实现工件，验证跨文件一致性，并编写计划人类或编码代理可以执行。

⭐ 规划管道被故意分解。本地模型通过专注的方式工作，而不是一个巨大的提示检索、实现检查、决策分解、决策解析、综合、工件生成和审查通过。

⭐ 安全带具有精确性。fitz-sage检索、结构索引、AST传递、调用图、基础检查，工件集闭包检查可以捕捉到只提示计划往往会遗漏的错误类别。

⭐ 评估是围绕黄金计划分类法建立的。对于基准测试任务，像Claude Sonnet这样的强大模型会有所帮助编写理想的计划分类法，并根据明确的答案对生成的计划进行评分。

严菲茨纳(领英, GitHub, 抱抱脸).

为什么 `fitz-forge`?

计划工件作为合同🧾

每个作业都会生成一个带有代码库上下文、实现状态、决策、拟议工件的标记工件，审查发现、风险和验证命令。该计划旨在被检查、交给编码代理或使用一位人类工程师。

利用本地模型🧠

当线束将每次调用缩小到模型可以可靠地完成的事情时，本地编码模型就更有用了：检查这个上下文，解决这个决定，写这个工件，批评这个阶段。

基于代码库的上下文🗂️ → 代理上下文收集

fitz-sage检索、结构索引、接口签名、导入上下文和AST导出的摘要为在做出设计决策之前规划管道。

高级工程师审核层🧑‍💼 → 高级工程师评审

狭义的审查通过了批评分解、假设、架构、设计、语义工件质量和工件新闻报道。失败的审查可以重新生成受影响的阶段；审核通过失败后，原始输出保持不变。

封闭工件集🔒

工件生成是作为一个集合进行检查的，而不是一次只检查一个文件。闭包检查查找丢失的跨文件符号，未解析的导入、无效的kwargs、异步/同步误用和键入的字段访问错误。

MCP就绪工作流程🔌

CLI和MCP服务器共享相同的服务层。 fitz-forge 可以独立运行或坐在Claude Desktop后面， Claude Code、Codex或其他支持MCP的客户端。

本地首次执行🏠

Ollama、LM Studio和llama.cpp都支持本地后端。作业存储在SQLite中，可以恢复长时间运行从检查站。

规划工件

fitz-forge 将计划视为输出合同。

它不是一个有保证的补丁生成器。工件代码旨在足够具体，以便人类或编码代理检查、调整和实施。

部分	含义	你能用它做什么
上下文	相关存储库文件、结构摘要、接口签名和约束。	看看这个计划有什么依据
实施状态	请求的行为是否已经存在，有证据和差距。	避免重新实施已完成的工作或围绕真正缺失的部分制定计划。
决策	分解架构决策，并根据基本原理解决选择。	在代码生成或代理切换之前审查设计。
人工制品	为关键实现部分提出的文件级代码工件。	检查混凝土代号形状，及早发现错误接口。
评论	高级工程师对假设、架构、设计、工件和覆盖范围的批评。	决定计划是否已准备就绪或需要另一个周期。
路线图	分阶段实施步骤、验证命令和风险说明。	将工作交给编码代理或手动执行。

管道

管道文件 • 建筑 • 配置

fitz-forge 在LLM调用之间运行具有确定性代码分析的10阶段规划管道。

重要的设计选择是 高级工程师审查层包裹着管道.它的批评范围很窄仅限于一个阶段的输出，然后在审查标记问题时重新生成受影响的阶段。

     USER PROMPT
          │
          ▼
┌─── 🧑‍💼 SENIOR ENGINEER REVIEW LAYER ───────────────────────────────┐
│   detect → regenerate → re-review → keep whichever is better      │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐      │
│  │                                                         │      │
│  │   1. Agent Context Gathering       [6-8 LLM]            │      │
│  │   2. Implementation Check          [1 LLM]              │      │
│  │   3. Call Graph Extraction         [0 · AST]            │      │
│  │   4. Decision Decomposition        [2-4 LLM]   ◂───────────────── decomposition review
│  │   5. Decision Resolution           [10-15 LLM]          │      │
│  │   6. Synthesis                     [~18 LLM]            │      │
│  │      ├─ context assumptions                    ◂───────────────── assumption review
│  │      ├─ architecture pick                      ◂───────────────── architecture review
│  │      └─ design spec                            ◂───────────────── design review
│  │   7. Artifact Generation           [3-8 LLM]            │      │
│  │      ├─ per-file code                          ◂───────────────── semantic review
│  │      └─ set-level coverage                     ◂───────────────── coverage review
│  │   8. Grounding Validation          [0-5 LLM]            │      │
│  │   9. Coherence Check               [1 LLM]              │      │
│  │  10. Render + Write                [0]                  │      │
│  │                                                         │      │
│  └─────────────────────────────────────────────────────────┘      │
│                                                                   │
│  Fail-safe: any review error keeps the original output unchanged. │
└───────────────────────────────────────────────────────────────────┘
          │
          ▼
    ~/.fitz-forge/plans/plan_<id>.md

#	阶段	它的作用	文档
1	代理上下文收集	检索并压缩代码库上下文。	01_代理织物采集.md
2	实现检查	询问请求的行为是否已经存在。	02_实施-检查.md
3	调用图提取	构建确定性调用图上下文。	03_全图导出.md
4	决策分解	将任务分解为架构决策。	04_决策分解.md
5	决策解决	根据代码证据解决每个决策。	05_决议.md
6	综合	构建计划形状和设计。	06_合成材料.md
7	工件生成	生成建议的代码工件。	07_艺术一代.md
8	接地验证	对照存储库检查生成的内容。	08_循环验证.md
9	一致性检查	检查跨阶段一致性。	09_连贯性检查.md
10	渲染+编写	编写最终的降价计划。	-

[！注意] 目前Python繁重的基准测试路径大约是45-70个LLM调用，在RTX 5090上大约需要8-12分钟。硬件，模型、源大小和可选的审阅设置会大大改变这一点。

评估

评分器V2规格 • 分类示例 • 黄金计划创作工具

核心评估问题很简单：

当还没有一个正确的补丁时，如何对计划工件进行评分？

fitz-forge 用特定任务的黄金计划分类法来回答这个问题。对于每个基准挑战，一个前沿模型，例如 Claude Sonnet用于检查目标存储库并起草理想的规划工件：正确的架构、重要的文件、预期的实现形式和常见的错误方法。该草案被审查为在对局部模型输出进行评分之前进行分类。

分类层	它捕获了什么
架构层次	计划是否选择了正确的实施形式或降级的替代方案。
所需文件	哪些文件必须被触摸，哪些是可选的，哪些是分散注意力的。
人工制品标准	每个关键代码工件必须包含什么。
故障模式	存根、伪造的API、错误的请求字段、缺失的流行为、未接地的导入和类似的缺陷。
验证形状	应证明实施有效的命令和检查。

流媒体功能的示例架构层：

等级	含义	分数
`A1`	保留全部现有管道；最后一代正确地流式传输令牌。	100
`A2`	流媒体可以工作，但绕过了部分合成抽象。	75
`A3`	直接调用提供者流并跳过检索/上下文逻辑。	30
`A4`	调用阻塞应答路径并拆分完成的文本。	10
`A5`	放弃、终止或错过该功能。	0

评分者将确定性检查与分类法分类相结合。确定性检查可以捕捉到精确的故障，例如缺少所需文件、解析错误、， NotImplementedError, sys.stdout，失踪 yield，伪造符号，未解决导入、跨工件方法不匹配和无效的路线图命令。然后，分类学分类绘制了计划的将架构和关键工件放在金钥匙上。

[！注意] 正常使用期间生成的计划不得分。记分器是一个离线评估工具，用于衡量规划管道，并将原始本地模型输出与线束内的相同模型进行比较。

📦 Quick Start

安装

pip install fitz-forge

可选附加功能：

pip install "fitz-forge[api-review]"  # Anthropic API review pass
pip install "fitz-forge[dev]"         # pytest, ruff, build tools

配置

fitz-forge prep

先决条件：

Python 3.10+
一个本地LLM后端：奥拉玛, LM 工作室，或 llama.cpp
菲茨圣人用于代码检索

跑

fitz-forge plan "Build a plugin system for data transformations"

未运行的队列：

fitz-forge plan --detach "Build a plugin system for data transformations"
fitz-forge run
fitz-forge list
fitz-forge get <id>

开发安装

git clone https://github.com/yafitzdev/fitz-forge.git
cd fitz-forge
pip install -e ".[dev]"

📦 CLI Reference

fitz-forge prep                 # Configure local model provider
fitz-forge plan "description"   # Create and run a planning job inline
fitz-forge plan --detach "..."  # Queue only
fitz-forge run                  # Process detached queued jobs
fitz-forge list                 # Show jobs
fitz-forge status <id>          # Check progress
fitz-forge get <id>             # Print completed plan
fitz-forge resume <id>          # Resume failed/interrupted job with live UI
fitz-forge retry <id>           # Re-queue failed/interrupted job
fitz-forge confirm <id>         # Approve optional API review
fitz-forge cancel <id>          # Skip optional API review
fitz-forge serve                # Start MCP server

作业生命周期：

QUEUED → RUNNING → COMPLETE
                  → AWAITING_REVIEW → QUEUED (confirm) / COMPLETE (cancel)
                  → FAILED / INTERRUPTED (both retryable)

📦 MCP Usage

对于Claude Desktop、Claude Code或其他支持MCP的客户端：

{
  "mcpServers": {
    "fitz-forge": {
      "command": "fitz-forge",
      "args": ["serve"]
    }
  }
}

暴露的MCP工具：

工具	说明
`create_plan`	排队计划作业
`check_status`	检查作业进度
`get_plan`	检索已完成的计划
`list_plans`	列出计划工作
`retry_job`	重试失败/中断的作业
`confirm_review`	批准API可选审核
`cancel_review`	跳过可选的API审核

📦 Architecture → Full Architecture Guide

┌─────────────────────────────────────────────────────────────────┐
│                         fitz-forge                              │
├─────────────────────────────────────────────────────────────────┤
│  User Interfaces                                                │
│  CLI: prep | plan | run | list | status | get | serve           │
│  MCP: create_plan | check_status | get_plan | retry_job         │
├─────────────────────────────────────────────────────────────────┤
│  Shared Service Layer                                           │
│  fitz_forge/tools: CLI and MCP call the same operations          │
├─────────────────────────────────────────────────────────────────┤
│  Job Store                                                       │
│  SQLiteJobStore: queued jobs | state | checkpoints | plans       │
├─────────────────────────────────────────────────────────────────┤
│  Worker                                                         │
│  BackgroundWorker: sequential execution and crash recovery       │
├─────────────────────────────────────────────────────────────────┤
│  Planning Pipeline                                               │
│  retrieval | decisions | synthesis | artifacts | validation      │
├─────────────────────────────────────────────────────────────────┤
│  LLM Providers                                                   │
│  Ollama | LM Studio | llama.cpp | optional Anthropic review      │
└─────────────────────────────────────────────────────────────────┘

主要模块：

模块	角色
`fitz_forge/cli.py` 键入CLI。
`fitz_forge/server.py`	FastMCP服务器
`fitz_forge/tools/`	CLI和MCP的共享服务层
`fitz_forge/models/`	SQLite作业存储和作业状态模型
`fitz_forge/background/`	工作人员生命周期和崩溃恢复
`fitz_forge/llm/`	Ollama，LM Studio，calla.cpp客户端
`fitz_forge/planning/`	规划流程、审查、工件、验证
`benchmarks/`	内部评估工具和挑战任务

📦 Configuration → Full Configuration Guide

fitz-forge prep 创建本地配置文件和作业数据库。配置选择LLM后端、模型、上下文长度，源目录行为、输出目录和可选的Anthropic审查设置。

平台	配置路径
窗户	`%LOCALAPPDATA%\fitz-forge\fitz-forge\config.yaml`
macOS	`~/Library/Application Support/fitz-forge/config.yaml`
Linux	`~/.config/fitz-forge/config.yaml`

支持的本地提供商是Ollama、LM Studio和llama.cpp。

📦 Boundaries / Troubleshooting

这是编码代理吗？

不是单独的。 fitz-forge 是一种规划工具。它制定了一个有根据的实施计划和拟议的工件；另一个编码代理或人类仍然应用该补丁。

生成的工件是否保证干净应用？

不，它们是具体的规划工件，不是正确性的保证。关闭和接地检查非常重要失败类，但生成的代码仍需要审查和测试。

哪些代码库最有效？

当前的实现在Python代码库上最为成熟。支持TypeScript的基础设施存在，但应该被视为实验性的。

基准分数是否适用于正常计划？

不是。基准分数是离线评估信号。除非运行基准测试，否则不会对正常的计划作业进行评分安全带。

为什么跑步需要几分钟？

该管道有意将计划分解为许多小型LLM调用和审查通道。这使得本地模型更加可靠，但比一次性提示慢。

发展🧪

pytest
ruff check fitz_forge/
ruff format --check fitz_forge/ tests/

这是阿尔法软件。在发布版本或使用基准数字作为项目之前，将CI失败视为阻碍因素声称。

许可证

麻省理工学院

链接

文档：

使用说明

菲茨锻造厂

本地LLM的代理编码规划工具。

从何开始🚀

关于

为什么 fitz-forge?

规划工件

管道

评估

安装

配置

跑

开发安装

发展🧪

许可证

链接

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器

为什么 `fitz-forge`?