菲茨锻造厂
本地LLM的架构编码规划工具
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 阅读你的代码库,分阶段推理,自我批评,
并提取小模型实际上可以可靠地产生的结构化输出。
从哪里开始🚀
> [!重要]
> 需要 奥拉玛, LM工作室,或 llama.cpp
> 装载模型。还需要 菲茨圣人 用于代码检索。```bash
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建造(领英, GitHub).
______________________________________________________________________
### 为什么 `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
| # | 阶段 | 文档 |
|---|---|---|
| 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 | 渲染+写入 | -- |
> [!注意]
> 管道将一个会淹没小模型的问题分解为许多它可以可靠处理的小LLM调用。
> 每个字段的JSON提取不到2000个字符——小到足以让3B量化模型产生有效输出。
> 确定性AST工作(调用图、接地检查)承载结构载荷,因此LLM只做LLM擅长的事情。
完整的管道文档: 文档/功能/ --涵盖每个阶段和基础设施组件的详细文档。
📦 Quick Start```bash
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
**可选附加功能:**```bash
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+
- 奥拉玛, LM工作室,或 llama.cpp 装载模型
- 菲茨圣人 用于代码检索
📦 CLI Reference```bash
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
插入克劳德代码或克劳德桌面:```json
{
"mcpServers": {
"fitz-forge": {
"command": "fitz",
"args": ["serve"]
}
}
}
**MCP工具:**
|工具|说明|
|------|-------------|
| `create_plan` |排队新的计划作业|
| `check_status` |检查作业进度|
| `get_plan` |检索已完成的计划|
| `list_plans` |列出所有规划工作|
| `retry_job` |重试失败的作业|
| `confirm_review` |看到成本后批准API审核|
| `cancel_review` |跳过API审查,最终确定计划|
______________________________________________________________________
📦 Configuration
首次运行时自动创建:
|平台|路径|
|----------|------|
|窗户| `%LOCALAPPDATA%\fitz-forge\fitz-forge\config.yaml` |
|macOS| `~/Library/Application Support/fitz-forge/config.yaml` |
|Linux| `~/.config/fitz-forge/config.yaml` |
数据库(`jobs.db`)位于同一目录中。```yaml
# 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 <-- BackgroundWorker --> 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```bash
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测试管道更改:```bash
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
```
许可证
麻省理工学院
链接
- GitHub
- PyPI
- 更新日志
- 建筑
- 功能文档 --17份详细文件,涵盖每个管道阶段和基础设施组成部分
- 配置参考 --解释每个配置字段
- 故障排除 --GPU问题、Windows怪癖、管道调试
- 贡献
- 示例
