BeanBot

Build Status

Maven Central

NetBeans

License

NetBeans 에디터 내부에 존재하는 AI 페어 프로그래머 — IDE를 벗어나지 않고 질문하고, 설명하고, 코드를 생성하고 리팩토링할 수 있습니다.

BeanBot은 Agent Client Protocol (ACP)을 통해 통합된 AI 기능을 제공하도록 설계된 NetBeans IDE 플러그인입니다. 이 플러그인은 코드 생성, 프로젝트 분석, 자동화된 작업 실행 등 기술 지원을 위한 구조화된 채팅 인터페이스를 제공합니다.

UI Screenshot 1	UI Screenshot 2	UI Screenshot 3

시작하기 (Getting Started)

설정, 기능 세부 정보 및 사용 지침은 사용자 가이드를 참조하십시오.

지원되는 코딩 하네스(coding harnesses): Oh My Pi, OpenCode, OpenClaw, Pi, Goose, Cursor, Copilot, Claude, Hermes, Gemini, Devin — 온보딩 중 또는 나중에 도움말 메뉴에서 하나를 선택하세요.

토큰 및 비용 통계는 외부 프로세스가 아닌 ACP 트래픽 자체에서 기록됩니다. 사용량 업데이트 및 턴당 토큰 수치는 하네스가 이미 전송하는 것이므로, NetBeans 사용자 디렉터리(beanbot/usage-stats.mv.db)에 임베디드 H2 데이터베이스로 기록되어 재시작에도 살아남고 하네스를 실행하지 않아도 읽을 수 있습니다. 툴바의 통화 버튼을 누르면 패널이 열리고, 이 패널은 모델별 및 에이전트별로 수치를 분해하여 보여줍니다. 이는 사용량을 불완전하게 보고하는 하네스의 경우 근사치입니다.

테스트 구성 (Test Configuration)

시간 제약으로 인해 테스트는 주로 이 구성을 기반으로 수행되었습니다. 플러그인은 다른 버전/운영체제에서도 작동해야 하지만, 사용자 경험은 다를 수 있습니다.

소스에서 설치하기

1. 저장소 복제:
   복사

   git clone https://github.com/anandb/nb-complete.git
   cd nb-complete
   

   1

   2

   3
2. 패키지 빌드:
   복사

   mvn package -DskipTests
   

   1

   2
3. 생성된 NBM은 ./target/nbm/ 디렉토리에 위치합니다.
4. NetBeans 플러그인 관리자(Plugin Manager)를 통해 플러그인을 설치하세요.

아키텍처 (Architecture)

이 프로젝트는 NetBeans Platform에 통합된 육각형(Hexagonal, 포트 및 어댑터) 아키텍처를 따릅니다:

• model/: ACP을 준수하는 데이터 레코드 (세션, 메시지, 업데이트, 설정 옵션). 상위 계층과의 의존성이 없습니다.
• contract/: 세션 제어, 프로세스 관리, UI 콜백에 대한 포트를 정의하는 서비스 인터페이스. manager/가 구현하고, ui/가 사용합니다.
• manager/: 핵심 오케스트레이션 — 프로토콜 클라이언트 (stdin/stdout을 통한 JSON-RPC), 세션 상태 머신(state machine), 프로세스 생명 주기, SSE 전략 디스패치.
• mcp/: MCP 서버 통합 — IDE 도구 세트(편집기 컨텍스트 및 탐색, 파일 시스템, git/hg, 작업(tasks), 프로젝트, stash diff)를 등록하는 로컬 서버를 호스팅하여 AI 클라이언트가 열린 탭을 검사하고 편집기 탐색을 제어할 수 있게 합니다.
• project/: NetBeans 생명 주기 후크 (@OnStart/@OnStop), 열린 프로젝트 관리자, 그리고 markdown 프로젝트 유형.
• tasks/: todo.txt 작업 저장소 통합 — 버그 추적 제공업체(bugtracking providers), 이슈 캐시, 작업 편집기.
• support/: 순수 유틸리티 — 로깅, JSON 매핑, 텍스트 스캐닝, 상수, 브라우저 도우미. 상위 계층과의 의존성이 없습니다.
• ui/: 모든 Swing 컴포넌트 — 채팅 창, 메시지 버블, 스트리밍 애니메이션, 테마 지정(theming), 옵션 패널, stash diff 뷰어. contract/ 인터페이스와 model/ 데이터 레코드, support/ 유틸리티에 의존하며, 오직 ui/platform/ 브릿지를 통해서만 project/ 계층에 의존합니다. 절대 manager/나 mcp/를 임포트하지 않습니다.

계층별 의존성 (Layer Dependencies)

의존성은 아래로만 흐르며, 계층 간에는 상향 임포트를 하지 않습니다:

┌─────────┐
│ ui/ │ ← presentation (가장 상위)
└────┬────┘
...

연결 흐름 (Connection Flow)

┌──────────┐    SSE / JSON-RPC    ┌───────────────────┐
│  사이드바 │ ◄──────────────────► │ AcpProtocolClient │
│ (클라이언트) │     stdin/stdout     │    (전송 계층)    │
...

project/, mcp/, 및 tasks/는 이 다섯 계층 모델 외부에 위치합니다. project/는 NetBeans 라이프사이클 와이어링(lifecycle wiring)을 담당하고, mcp/는 도구 서비스 어댑터 표면(tool-serving adapter surface)이며, tasks/는 자체 포함된 버그 추적 기능입니다. model/, contract/, 및 support/는 이들 중 어느 것도 가져오지 않습니다. manager/는 오직 ProcessManager로부터만 mcp/에 접근합니다 (이를 위해 McpManager/McpToolAdapter를 사용함).

소스 코드 구성 (Source Organization)

모든 소스 코드는 src/main/java/github/anandb/netbeans/ 아래에 있습니다:

코드 읽기 경로 (Code Reading Path)

플러그인의 실행 흐름에 맞춰 안내된 워크스루를 위해서는 다음 순서로 파일을 읽으세요:

단계 1: 진입 및 라이프사이클 (Phase 1: Entry & Lifecycle)

1. project/ACPStartup.java — NetBeans @OnStart 후크
2. project/ACPShutdown.java — @OnStop 정리 작업
3. src/main/resources/github/anandb/netbeans/ui/layer.xml — NetBeans 등록 (창 메뉴/바로가기, 에디터 팝업, Git 도구 모음); 옵션 패널은 ui/ACPOptionsPanelController.java에서 어노테이션을 통해 등록됩니다.

2단계: 서버 프로세스 (Server Process)

4. manager/ProcessManager.java — ACP 서버 서브프로세스를 소유하고 중앙 요청 디스패치 허브 역할을 수행합니다. 자체 생성(spawn itself)은 manager/ServerProcessLifecycle.startServer()에서 이루어지며, 사용자가 선택한 하네스 바이너리(11개 지원)를 실행합니다.
5. support/BinaryResolver.java — PATH에서 바이너리를 찾습니다.
6. manager/AcpProtocolClient.java — stdin/stdout을 통한 JSON-RPC, SSE 읽기 루프, 보류 중인 요청 추적

3단계: 세션 관리 (Session Management)

7. manager/SessionManager.java — 세션 CRUD, 상태 기계(state machine), SSE 라우팅
8. manager/SessionStateMachine.java — 세션 라이프사이클을 위한 유한 상태 기계(Finite-state machine)
9. model/Session.java — 세션 데이터 레코드
10. model/SessionUpdate.java — SSE 알림 페이로드 모델
11. model/Message.java — 메시지 모델 (프롬프트, 도구 호출(tool calls), 결과)

4단계: 전략 디스패치 (Strategy Dispatch) (SSE 핸들러 체인)

12. contract/UIHandler.java — 렌더링을 위한 콜백 인터페이스
13. manager/strategy/StrategyRegistry.java — 유일한 디스패치 클래스: 타입 스위치가 SessionUpdate → 추출 로직을 라우팅하여 전략 인터페이스 계층 구조를 제거합니다.

5단계: UI 렌더링 (UI Rendering)

14. ui/AssistantTopComponent.java — 메인 채팅 창 (NetBeans TopComponent)
15. ui/ComponentLifecycleHandler.java — 라이프사이클 이벤트를 관리자(managers)에 연결함
16. ui/SessionLifecycleHandler.java — 접착제 역할: SSE 업데이트를 수신하고, StrategyRegistry.handle()을 호출하며, UI를 실행함
17. ui/ChatThreadPanel.java — 스트리밍 애니메이션이 적용된 메시지 버블의 흐름(thread)
18. ui/MessageBubble.java — 개별 메시지 턴 (생각, 도구, 코드 세그먼트)
19. ui/MessageSender.java — 전송/취소 로직

6단계: 지원 기능 (Supporting)

20. model/ProcessedMessage.java — UI가 소비하는 렌더링된 출력 모델
21. mcp/McpManager.java — MCP 서버 통합 계층
22. contract/RequestHandler.java — 서버로부터 들어오는 RPC 요청을 위한 인터페이스

시스템 속성 (System Properties)

플러그인은 다음 시스템 속성과 환경 변수를 읽습니다:

속성 파일 형식

The 색상 속성은 colors.json에 선언되어 있으며 다음을 포함합니다: 배경(background), 전경(foreground), 선택(selection), 강조(accent), 오목한 배경(sunken background), 버블(bubble)(사용자/어시스턴트), 코드(code), 테이블(table), 헤더(header), 생각(thinking), 도구(tool), 권한(permission), 오류(error) 색상. 대부분의 항목은 밝은 모드와 어두운 모드 변형을 모두 정의하지만, UIManager 키나 단일 폴백(foreground, sunkenBackground, codeBackground, codeForeground, codeSelection)에서 직접 해결되는 것은 그렇지 않습니다.

작업 파일 형식 (Tasks File Format)

BeanBot의 작업(Tasks) 저장소는 일반적인 todo.txt 파일로 저장되므로, 모든 표준 todo.txt 도구에서 읽고 편집할 수 있습니다. 각 작업은 한 줄이며, 형식은 todo.txt 사양을 기반으로 하되 BeanBot 전용의 작은 확장 세트를 추가합니다.

라인 레이아웃 (Line layout)

x (B) 2026-08-02 2026-08-01 Fix the bug @urgent @bug +myproject due:2026-09-01 id:t-1a2b3c4d estimate:5 consumed:2 upd:2026-08-02T10:00:00Z

참고 및 규칙 (Notes & conventions)

• 태그와 프로젝트는 오직 @/+ 토큰으로만 저장됩니다. 따라서 중복되는 tags:/projects: 미러가 없으므로, 로드→저장 왕복 과정에서 절대 중복되지 않습니다.
• estimate/consumed은 BeanBot이 의미를 부여하지 않는 임의의 사용자 정의 단위를 나타내는 정수입니다. 이는 개인적인 추적 용도일 뿐입니다.
• 알 수 없는 토큰은 읽기 시 허용됩니다: @/+도 아니고 인식된 key:value 형식도 아닌 토큰은 자유 텍스트 요약으로 흡수되므로, 다른 todo.txt 도구로 편집된 파일도 여전히 읽을 수 있습니다.
• 파싱 가능한 내용이 없는 줄(빈 줄)은 건너뜁니다. id: 토큰이 없는 줄이라도 여전히 파싱되며 — 새로운 id가 생성됩니다.

문제 해결 (Troubleshooting)

알려진 문제/제한 사항 (Known Issues/Limitations)