Fitz Graveyard

菲茨锻造厂

本地LLM的架构编码规划工具

 ](https://pypi.org/project/fitz-forge/)  ](CHANGELOG.md)  

问题 • 洞察力 • 为什么选择fitz forge？ • 基准测试 • 运作原理 • 文档 •

______________________________________________________________________

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 (no harness)

"Add a WebSocket endpoint. Use the websockets library. Create a new file for handlers. Add authentication middleware."

Generic advice. No file paths. No awareness of existing code. Hallucinated library choice. Would break the existing architecture.

🔨 fitz-forge (same model, same hardware)

Phase 1: Extend ChatRouter in api/routes/chat.py - Add ws_chat() using existing ChatEngine - Reuse AuthMiddleware.verify_token() - Test: pytest tests/api/test_chat_ws.py

阶段2：在schemas/chat.py中调整MessageSchema

• 添加ws_message字段（与现有字段匹配

ChatMessage.content结构）

• 验证：pydantic模型验证（）

真实文件。真正的方法。分阶段路线图 使用验证命令。基于 实际的代码库。

→ 同样的型号，同样的硬件。区别在于线束： fitz-forge 阅读你的代码库，分阶段推理，自我批评， 并提取小模型实际上可以可靠地产生的结构化输出。

______________________________________________________________________

从哪里开始🚀

\[！重要\] 装载模型。还需要 菲茨圣人 用于代码检索。

pip install fitz-forge

fitz plan "Add OAuth2 authentication with Google and GitHub providers"

就是这样。你的计划在本地硬件上过夜。

______________________________________________________________________

关于

我建造 fitz-forge 因为最好的人工智能编码工具非常危险地依赖API补贴定价。 Claude Code每月收费100美元 *今天* --大量补贴。当这些补贴减少时，仅规划阶段 （理解代码库、推理架构、制定结构化计划）可能比订阅成本更高。 fitz-forge 将昂贵的规划阶段转移到您已经拥有的硬件上。无API成本。没有数据离开您的网络。 随着本地模型的改进，您的计划也会免费改进。

没有LangChain。没有LlamaIdex。每一层都是从头开始编写的，代码检索由 菲茨圣人.

大约2万行Python。970+次测试。由Yan Fitzner建造(领英, ).

______________________________________________________________________

为什么 fitz-forge?

减少您的Opus账单——在本地规划，与Sonnet合作实施💸

代理规划是这个过程中最昂贵的部分，也是LLM最挣扎的地方。 fitz-forge 生成一个markdown工件，交给Sonnet实现。昂贵的代币从未达到您的API预算。

愚蠢的本地模型产生了聪明的计划🧠

流水线将任务分解为原子决策，根据相关文件解析每个决策，然后叙述已提交的 将决策转化为计划。突然之间，一个本地模型可以在一个提示中产生压倒它的计划。

在您拥有的任何硬件上运行🖥️

消费级GPU？模特们喜欢 Qwen3.6-35-a3b 或 Gemma4-26B-A4b 完成整个管道。只使用CPU的盒子还是微型VRAM？以10 tok/s的速度运行一个中型模型 一夜之间。当你睡着的时候，每秒的代币不再重要。

通过CLI和MCP进入Claude Code或Codex🔌

暴露 fitz-forge 作为MCP服务器(fitz serve)并且它成为Claude Code或任何支持MCP的客户端内的工具。 与CLI的原理相同。告诉克劳德用以下方式制定计划 fitz-forge，当你等待时，它会在本地完成繁重的工作。

任何代码库，任何语言🌐

Python、Go、Rust——检索层按文件结构和导入进行索引，基础层验证生成的 工件与代码库实际包含的任何内容。

排队作业。入睡放松。让它运行一夜。 🌙

每个阶段都会产生检查点。在20分钟的运行中，第15分钟停电？ fitz retry 拿起从 最后完成的阶段。

完全本地执行是可能的🏠

Ollama、LM工作室或llama.cpp。无需API密钥即可启动。

______________________________________________________________________

基准测试

待定

______________________________________________________________________

运作原理

一个10阶段的流程，将架构规划分解为小型、集中的LLM调用，与确定性调用交织在一起 AST工作。检索+实现检查为基于决策的推理核心（分解→ 解决→ 合成），然后 在编写计划之前，生成工件，检查闭包，并将其与真实的代码库相结合。

     USER PROMPT
          │
          ▼
┌─────────────────────────────────────────┐
│ 1. Agent Context Gathering    [6-8 LLM] │  retrieval + compression
├─────────────────────────────────────────┤
│ 2. Implementation Check       [1 LLM]   │  already built?
├─────────────────────────────────────────┤
│ 3. Call Graph Extraction      [0 · AST] │  deterministic
├─────────────────────────────────────────┤
│ 4. Decision Decomposition     [2-4 LLM] │  adaptive best-of-N
├─────────────────────────────────────────┤
│ 5. Decision Resolution        [10-15]   │  1 call per decision
├─────────────────────────────────────────┤
│ 6. Synthesis                  [~15 LLM] │  reasoning + 13 extractions
├─────────────────────────────────────────┤
│ 7. Artifact Generation        [3-8 LLM] │  per-artifact + closure checks
├─────────────────────────────────────────┤
│ 8. Grounding Validation       [0-5 LLM] │  AST + repair
├─────────────────────────────────────────┤
│ 9. Coherence Check            [1 LLM]   │  cross-stage sanity
├─────────────────────────────────────────┤
│ 10. Render + Write            [0]       │  markdown to disk
└─────────────────────────────────────────┘
          │
          ▼
    ~/.fitz-forge/plans/plan_.md

Total: ~40-60 LLM calls · ~7-9 min on RTX 5090

\[！注意\] 管道将一个会淹没小模型的问题分解为许多它可以可靠处理的小LLM调用。 每个字段的JSON提取不到2000个字符——小到足以让3B量化模型产生有效输出。 确定性AST工作（调用图、接地检查）承载结构载荷，因此LLM只做LLM擅长的事情。

完整的管道文档： 文档/功能/ --涵盖每个阶段和基础设施组件的详细文档。

______________________________________________________________________

📦 Quick Start

# Install
pip install fitz-forge

# Queue a job
fitz plan "Build a plugin system for data transformations"

# Start the background worker
fitz run

# Check on it
fitz status 1

# Read the plan
fitz get 1

可选附加功能：

pip install "fitz-forge[api-review]"    # Anthropic API review pass
pip install "fitz-forge[lm-studio]"    # LM Studio provider (openai SDK)
pip install "fitz-forge[dev]"          # pytest, build tools

先决条件：

• Python 3.10+
• 菲茨圣人 用于代码检索

______________________________________________________________________

📦 CLI Reference

fitz plan "description"   # Queue a planning job
fitz run                  # Start background worker (Ctrl+C to stop)
fitz list                 # Show all jobs
fitz status           # Check progress
fitz get              # Print completed plan as markdown
fitz retry            # Re-queue failed/interrupted job
fitz confirm          # Approve optional API review
fitz cancel           # Skip API review, finalize plan
fitz serve                # Start MCP server

作业生命周期：

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

______________________________________________________________________

📦 MCP Server

插入克劳德代码或克劳德桌面：

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

MCP工具：

______________________________________________________________________

📦 Configuration

首次运行时自动创建：

数据库(jobs.db)位于同一目录中。

# LLM provider: "ollama", "lm_studio", or "llama_cpp"
provider: lm_studio

lm_studio:
  base_url: http://localhost:1234/v1
  model: qwen3-coder-30b-a3b-instruct    # single model for retrieval + reasoning
  smart_model: null                        # null = use model for all tiers
  fast_model: null                         # null = use model for all tiers
  timeout: 600
  context_length: 65536                    # split reasoning auto-enables below 32768

ollama:
  base_url: http://localhost:11434
  model: qwen2.5-coder-next:80b-instruct
  fallback_model: qwen2.5-coder-next:32b-instruct  # OOM fallback (null to disable)
  timeout: 300
  memory_threshold: 80.0  # RAM % threshold to abort

llama_cpp:
  server_path: /path/to/llama-server
  models_dir: /path/to/models
  port: 8012
  fast_model:
    path: model.gguf
    context_size: 65536
    gpu_layers: -1
    flash_attention: true
    cache_type_k: q8_0
    cache_type_v: q8_0

agent:
  enabled: true
  max_file_bytes: 50000
  max_seed_files: 50    # files available via inspect_files/read_file tools
  source_dir: null      # null = cwd at runtime

confidence:
  default_threshold: 0.7
  security_threshold: 0.9

anthropic:
  api_key: null  # null = API review disabled
  model: claude-sonnet-4-5-20250929

output:
  plans_dir: .fitz-forge/plans
  verbosity: normal

______________________________________________________________________

📦 Architecture → Full Architecture Guide

CLI (typer)   --> tools/ --> SQLiteJobStore  PlanningPipeline
MCP (fastmcp) --> tools/ --> SQLiteJobStore

fitz_forge/
├── cli.py                     # Typer CLI (9 commands)
├── server.py                  # FastMCP server + lifecycle
├── __main__.py                # python -m fitz_forge (MCP stdio)
├── tools/                     # Service layer
├── models/                    # JobStore ABC, SQLiteJobStore, JobRecord
├── background/                # BackgroundWorker, signal handling
├── llm/                       # LLM clients (Ollama, LM Studio, llama.cpp), retry
├── planning/
│   ├── pipeline/stages/       # 3 stages (split or combined) + orchestrator + checkpoints
│   ├── agent/                 # Code retrieval bridge to fitz-sage
│   ├── prompts/               # Externalized .txt prompt templates
│   └── confidence/            # Per-section confidence scoring
├── api_review/                # Anthropic review client + cost calculator
├── config/                    # Pydantic schema + YAML loader
└── validation/                # Input sanitization

______________________________________________________________________

📦 Development

git clone https://github.com/yafitzdev/fitz-forge.git
cd fitz-forge
pip install -e ".[dev]"  # editable install for development
pytest  # 970+ tests

# Lint
ruff check fitz_forge/
ruff format --check fitz_forge/ tests/

看 贡献.md 完整的开发指南和 示例/ 作为使用示例。

标杆工厂 对于A/B测试管道更改：

# Retrieval benchmarks (~12s/run)
python -m benchmarks.plan_factory retrieval --runs 10 --source-dir ../your-project

# Reasoning benchmarks with fixed retrieval
python -m benchmarks.plan_factory reasoning --runs 5 --source-dir ../your-project \
  --context-file benchmarks/ideal_context.json --split --max-seeds 5

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

链接

• PyPI
• 更新日志
• 建筑
• 功能文档 --17份详细文件，涵盖每个管道阶段和基础设施组成部分
• 配置参考 --解释每个配置字段
• 故障排除 --GPU问题、Windows怪癖、管道调试
• 贡献
• 示例