FABULA

'완료(done)'라는 말만 믿지 않는, 로컬 우선의 코딩 에이전트.

The 엔진은 프로젝트 자체 테스트가 통과할 때까지 실행을 지속하며, 모든 성공적인 실행 기록(green run)은 누구나 재현할 수 있는 영수증을 남깁니다.

Platform

Release

설치(Install) · 사용해보기(Try it) · 측정되는 것과 그렇지 않은 것 · 영수증 사양(Receipt spec) · 플러그인(Plugins) · 문서(Docs)

English · 中文 · Русский

개요 (What it is)

FABULA는 하나의 모델을 하나의 기기에서 구동하도록 설계된 코딩 에이전트입니다. LM Studio나 MLX를 통해 제공되는 작은 로컬 모델, 또는 이미 가지고 있는 모든 OpenAI-compatible 엔드포인트를 사용합니다. 이는 MiMoCode의 포크(fork)를 기반으로 구축된 데스크톱 앱(macOS) 및 웹 UI가 포함된 로컬 서버(Linux, Windows)입니다. MiMoCode 자체는 OpenCode 포크(무엇을 의미하는지)입니다.

핵심 전제: 신뢰성은 모델 주변의 메커니즘에 존재하며, 모델 그 자체에 있지 않습니다. 작은 모델은 자신이 아닐 때도

테스트가 포함된 프로젝트에서는 편집이 완료되었다고 간주하려면, 해당 프로젝트 자체의 테스트를 실행하여 녹색(green) 상태여야 합니다. 조기에 중단되는 턴은 엔진에 의해 작업으로 되돌려집니다. 소스 코드가 수정되었으나 검증되지 않았거나, 마지막 실행 결과가 빨간색(red)이었거나, 모든 편집이 적용되지 않았거나, 도구가 사용되었지만 테스트가 실행되지 않은 경우 등이 해당됩니다. 재진입 횟수는 제한적이며, 그 이후에는 명시적으로 **완료 안됨 (NOT DONE)**으로 종료되고 조용히 끝나지 않습니다. /goal을 사용하면 심사관(judge)은 모델의 요약이 아닌 기록된 궤적(trajectory) 자체를 읽고, 모순되는 '완료' 상태를 무효화할 수 있습니다.

상태: 이 문제는 측정됩니다. 한 SWE-bench Pro 캠페인에서 16회 세션 중 15회가 테스트를 실행하지 않았습니다. 가드(guard)가 결과에 미치는 영향은 아직 측정되지 않았습니다.

2. 모든 녹색 실행은 재현 가능한 영수증을 남깁니다

녹색 실행은 완료 증명 (Proof-of-Done) 영수증을 생성합니다: diff, 기본 커밋(base commit), 정확한 검증 명령 및 그 결과, 작업을 수행한 모델, 그리고 작업이 이루어진 컨텍스트의 지문입니다. fabula receipt verify는 기록된 기본값에 패치를 적용하고 임시 작업트리(throwaway worktree)에서 해당 명령을 다시 실행합니다.

이것이 무엇인지 명확히 하자면: 서명(signature)이 아니라 **재현 가능한 기록(replayable record)**입니다. 이는 이 패치가 이 기본값 위에서, 지금 당신의 기계에서, 이 명령을 통과한다는 것을 보여줍니다. 테스트가 의미 있는지를 증명하는 것은 아닙니다 — diff를 읽어보세요. 형식은 오픈 스펙입니다: verified-autonomy receipt v0.2.

3. 하나의 작은 모델과 하나의 추론 슬롯을 위해 제작되었습니다

• 프롬프트 접두사(prompt prefix)는 작업 내에서 바이트 안정적(byte-stable)으로 유지되므로, 모델의 KV 캐시가 매 단계마다 모든 것을 다시 읽을 필요 없이 남아 있습니다.
• **압축 측정(Compaction)**은 창이 가득 찼는지 결정하기 전에 프롬프트의 고정 비용을 측정합니다. 로컬 모델의 경우 시스템 프롬프트와 도구 스키마가 창의 대부분을 차지할 수 있으며, 모든 턴마다 고정된 비율만큼 압축됩니다.
• **로컬 어댑터(local adapter)**는 요청들이 경쟁적으로 실행되는 대신 단일 추론 슬롯에 대기열화합니다. 실제 턴이 먼저 진행되고, 백그라운드 작업은 기다리며, 너무 오래 기다린 요청은 동시에 실행되기보다는 재시도하라는 메시지를 받습니다.
• 선택적 가속 레인(Optional accelerated lane): ⚡로 표시된 모델(사변적 디코딩 (speculative decoding), 일반 디코딩과 동일한 출력)을 위해 마련되었으며, 해당 모델을 선택할 때 시작되고 다른 모델로 전환하면 중지되어 두 개의 실행 환경이 한 번에 큰 모델을 점유하지 않도록 합니다.
• 모든 문에 대한 가드(Guards on every door): 도구를 차단하는 규칙은 셸을 통해 동일한 것을 차단합니다. 컨테이너 없이 코드는 OS 커널 프로필 하에서 실행됩니다 (macOS에서는 Seatbelt, Linux에서는 bubblewrap). 모든 가져오기된 내용에는 SSRF 방지, 비밀 정보 마스킹(secret redaction), 프롬프트 주입(prompt-injection) 래핑이 적용됩니다.

23개의 플러그인과 62개의 도구가 선언된 순서로 로드되었습니다: docs/PLUGINS.md.

직접 사용해 보기: 실제 실행 재현하기

캡처된 실행은 있는 그대로 커밋됩니다. 이를 재현합니다:

cd demo && fabula receipt verify

VERIFIED ✓ — 아티팩트가 결정론적으로 재현되었습니다:
base c660a02ab138 + patch → `bun test` 통과.

더 어려운 것도 공개되어 있습니다: 하나의 실제 SWE-bench Pro 작업(qutebrowser)이 로컬 모델에 의해 하나의 소비자 기기에서 엔드투엔드로 해결되었으며, 벤치마크의 숨겨진 테스트에 의해 평가되었습니다 — 4개 중 4개가 통과 실패(fail-to-pass)를 거쳐 성공했으며, 회귀 현상도 없습니다 — docs/receipts/에서 단일 명령어로 Docker 재현이 가능합니다. 이것은 n = 1이며, 재현 및 논쟁을 위해 게시된 것이지 벤치마크 점수가 아닙니다.

또는 2분짜리 데모를 직접 실행해 보세요: 프로젝트로 demo/ 폴더를 열고(버그가 심어져 있어 모든 테스트가 어쨌든 녹색으로 통과합니다) *"내보내기 버그를 수정하세요: 야간 내보내기가 정확히 종료 날짜에 해당하는 행을 조용히 누락시킵니다. 증명해 보세요."*라고 요청합니다. 엔진은 편집 후 테스트가 모두 녹색으로 실행될 때까지 완료로 간주하지 않습니다.

측정되는 것과 측정되지 않는 것

FABULA는 종합적인 해결률(aggregate resolve rate)을 게시하지 않으며, docs/EVALS.md에서 그 이유와 어떤 것이 높은 수치를 얻게 하는지 설명합니다.

설치

git과 모델이 필요합니다 — 이 장치에서 실행되는 모델 또는 OpenAI와 호환되는 엔드포인트가 필요합니다. setup.sh는 엔진, Bun 및 네 개의 npm 패키지를 설치하고 종료됩니다. 사용자는 앱에서 모델을 선택합니다.

네 개의 npm 패키지, git, 그리고 엔진이 로컬 모델과 통신하는 localhost 어댑터가 설치됩니다. 요청하지 않은 큰 파일은 도착하지 않습니다. 네 가지 기능 중 추가할 수 있는 것은 사용자의 선택이며, 각기 비용이 따릅니다:

| 기능 | 비용 | 다음 경우 건너뛰기 |
|---|---|
| 실제 브라우저 구동 | Chromium 다운로드(~150 MB) | 코드를 위해 필요한 경우. 페이지를 읽는 것은 web_fetch이며, 어쨌든 설치됩니다. |
| ... |
./setup.sh --with=browser는 하나를 추가하고, --ask는 네 가지 모두를 안내하며, --all은 모든 것을 가져가고, --minimal은 어댑터조차 건너뜁니다.

macOS — 데스크톱 앱

Apple Silicon과 Xcode Command Line Tools(xcode-select --install)가 필요합니다.

git clone https://github.com/sergezuber/FABULA-LLM-5 && cd FABULA-LLM-5
./setup.sh
open FABULA-LLM-5.app

Linux

git clone https://github.com/sergezuber/FABULA-LLM-5 && cd FABULA-LLM-5
./setup.sh
bin/fabula serve --port 4096      # then open http://127.0.0.1:4096

데스크톱 창은 .deb 파일로 별도 빌드합니다: bash shell/build.sh.

Windows

먼저 Git for Windows를 설치하세요. 셸 가드는 하나의 POSIX 문법을 구문 분석(parse)하기 때문입니다.

git clone https://github.com/sergezuber/FABULA-LLM-5; cd FABULA-LLM-5
.	extbackslash setup.ps1
bin\fabula.exe serve --port 4096   # then open http://127.0.0.1:4096

언제든지 setup.sh를 다시 실행할 수 있습니다. 이 스크립트는 설치된 엔진이 소스보다 오래되었을 때만 재빌드하며, .env나 fabula.config.json 파일을 덮어쓰지 않습니다. 업데이트하려면: 앱을 종료하고, git pull && ./setup.sh를 실행한 후 다시 열면 됩니다.

모델 연결하기 (Point it at a model)

이 장치에서: LM Studio를 열고, 도구 호출(tool-calling) 모델을 로드한 다음, 해당 서버를 시작하세요. 설정은 이미 어댑터가 연결될 위치를 지정했습니다.

키는 .env (gitignore됨)에 넣고, fabula.config.json에서 제공업체를 설명하세요:

// .env
MY_API_KEY=sk-...

...

모델은 **도구 호출(tool calling)**을 지원해야 하며, limit에는 context와 output 모두가 필요합니다.

개인 정보 보호 (Privacy)

계정이나 원격 측정(telemetry)이 없습니다. 로컬 제공업체만 설정하면, 사용자의 프롬프트, 파일 및 채팅은 장치 내에 머무릅니다. 외부로 나가는 모든 것은 여기에 명시되어 있으며 — 이 목록이 약속입니다.

기본 설정 (세 개의 연결, 각각 스위치 포함):

• 업데이트 알림(Update notice) — GitHub에 어떤 릴리스가 가장 최신인지 문의하며, 사용자 정보는 전송하지 않습니다. 설정 ▸ 일반(Settings ▸ General)에서 비활성화할 수 있습니다.
• 모델 카탈로그(Model catalogue) — 시작 시와 매시간 https://models.dev/api.json을 가져와서 선택기(picker)가 컨텍스트 크기를 알도록 합니다. MIMOCODE_DISABLE_MODELS_FETCH=1로 비활성화할 수 있으며, MIMOCODE_MODELS_URL은 미러(mirror)를 가리키게 할 수 있습니다.
• 최초 사용 시 언어 서버(Language servers on first use) — 프로젝트가 필요로 할 때 GitHub 릴리스 또는 npm에서 다운로드됩니다. MIMOCODE_DISABLE_LSP_DOWNLOAD=1로 중지할 수 있습니다.

설정하거나 요청할 경우에만: 클라우드 모델(사용자가 제공하는 provider에 따라 무엇을 보는지 알 수 있음), 선택적 퀴즈 및 증명 게이트(보조 모델, 로컬 우선 사용), 그리고 호출하는 도구들 — 자체 SearXNG를 이용한 web_search, 지정된 페이지의 web_fetch 및 브라우저, FABULA_NTFY_TOPIC이 설정된 경우에만 ntfy.sh 알림을 의미합니다.

0.292.0 버전까지는 내장 엔진(vendored engine)에 기본 활성화되어 있던 분석 업로더가 있었습니다. 이 기능은 소스에서 삭제되었으며, 추적 엔드포인트가 소스 또는 배포된 바이너리에 다시 나타나면 빌드 게이트(no-phone-home.gate.test.ts)가 실패합니다.

문서 (Docs)

감사의 말씀 (Acknowledgements)

MiMoCode (OpenCode의 포크), LM Studio, SearXNG, Playwright, Bun, piper 및 faster-whisper를 기반으로 구축되었습니다. 여러 감독 메커니즘은 pi (Mario Zechner, MIT)에서 각색되었습니다. 더 보기: docs/CREDITS.md.

라이선스 (License)

FABULA 자체 코드는 MIT입니다 — LICENSE를 참조하십시오.

이 저장소의 대부분은 FABULA 자체 코드가 아닙니다. engine/은 MiMoCode (Xiaomi)의 내장 포크이며, 이는 OpenCode의 포크입니다 — 자체 저작권 보유자들에 의해 MIT 라이선스를 따릅니다 — 그리고 MIT가 취소하지 않는 추가 사용 제한 사항(engine/USE_RESTRICTIONS.md: 군사적 용도 금지, 악의적인 사이버 활동 금지, 인간 감독 없는 자율 고위험 행동 금지 등)을 포함하여 배포됩니다. 누가 무엇을 소유하는지, 상위(upstream) 개정판은 무엇인지, 그리고 분할을 어떻게 검증하는지에 대해서는 NOTICE.md를 참조하십시오.