opendoubao

OpenDoubao는 오픈소스 AI Agent 애플리케이션 생성 플랫폼으로, Doubao Work의 오픈소스 대안입니다. 핵심 개념은 자연어 채팅을 통해 즉흥적으로 고가용성 웹 프론트엔드/백엔드 애플리케이션을 생성하고, 이후 상호작용에서는 대형 언어 모델(LLM)에 의존하지 않아 안전하고 빠르고 안정적인 API 호출을 구현하는 것입니다. ## 핵심 아키텍처: 2단계 경험 프로젝트는 독특한 2단계 설계를 채택합니다: **1단계 – 생성 단계 (채팅 / AI 또는 규칙)**: 사용자가 대화로 요구사항을 설명하면 AI Agent가 해당 UI 화면을 생성하고 APIJSON 요청을 제안합니다. 요청은 검증 후 실행되며, 성공하면 bindRequest가 발송되어 템플릿과 매개변수 매핑(paramMap)을 UI 컨트롤에 바인딩합니다. **2단계 – 안정 상태 단계 (LLM 없음)**: 사용자가 이후 필터 조건, 정렬 방식, 페이지네이션 매개변수 등을 수정하면 BoundExecutor가 paramMap을 bodyTemplate에 직접 병합하고 HTTP POST를 통해 APIJSON 인터페이스를 호출합니다. 토큰을 전혀 소비하지 않으며 응답 속도가 빠르고 안정적입니다. ## Agent-to-API 프로토콜 (A2API) 프로젝트는 A2API 0.1 프로토콜을 정의하며, 봉투 형식은 { "version": "0.1", "type": ... }입니다. 포함된 메시지 유형은 다음과 같습니다: - **proposeRequest**: 후보 APIJSON 호출 - **reviseRequest / decision**: 요청 수정 또는 승인/거부 - **bindRequest**: code == 200 후 템플릿과 paramMap을 생성하여 UI 구동 호출에 제공 - **requestResult / status**: 결과 및 상태 피드백 ## 보안 메커니즘 프로젝트에는 민감한 작업 승인 메커니즘이 내장되어 있습니다. 읽기 작업은 자동으로 실행되지만, 쓰기 작업(기본적으로 post, put, delete, gets, heads를 포함하며 SENSITIVE_METHODS 환경 변수로 재정의 가능)은 관리자가 Admin 백엔드에서 승인한 후에만 통과할 수 있습니다. 관리 백엔드는 Apply(신청서), Call logs(호출 로그), Stats(통계)의 세 가지 탭을 제공하며 Access, Request, Document, Chain에 대한 복잡한 승인 흐름을 지원합니다. ## 기술 스택 및 저장소 구조 - **런타임**: Node.js 18+, Vite(프론트엔드), Hono(API 서비스) - **데이터 계층**: APIJSONBoot-MultiDataSource(또는 호환 서비스), localhost:8080에서 실행 - **저장소 모듈**: - opendoubao: 오케스트레이터 + 채팅 UI(생성) + 바인딩 필터(안정 상태) - opendoubao-admin: 승인 구성, 승인 후 Access / Request / Document에 기록 - a2qpi/protocol: A2API 0.1 봉투, JSON Pointer, 검증기, CRUD 픽스처 테스트 - a2qpi/runtime: ApiJsonClient, HitlController, BoundExecutor ## 빠른 시작 cd ~/a2api cp .env.example .env npm install npm test npm run build npm run dev 시작 후 클라이언트는 http://localhost:5173 에서 실행되고, API 서비스는 http://localhost:3000, 관리 백엔드는 npm run dev:admin으로 시작하여 http://localhost:5174 에서 실행됩니다. ## 구성 및 확장 사용자는 오른쪽 상단의 Login에서 로그인/회원가입을 하고 AI Model, Base URL, API Key를 구성할 수 있습니다. 빠른 칩(예: 'List the latest 3 moments with authors')을 통해 신속하게 쿼리를 시작할 수 있습니다. 선택적으로 .env에 OPENAI_API_KEY를 설정하여 LLM 보조 Bootstrap을 활성화할 수 있습니다. 설정하지 않으면 내장 의도 규칙이 User / Moment / Comment 등의 엔티티를(중국어/영어 모두) 식별할 수 있습니다. 프로젝트는 다양한 데모 데이터 테이블(User, Moment, Comment 및 직원, 활동, 채팅, 뉴스, 정보, 블로그, 기사, 비디오, 음악, 상품, 주문, 배송지, 카테고리 등)을 제공하며, 가져온 후 Access/Request를 다시 로드해야 합니다. 쓰기 작업은 일반적으로 로그인된 세션이 필요하며(@role OWNER/LOGIN), MVP 단계에서는 요청을 생성하고 HITL 승인/거부 화면을 표시합니다. ## Agent 자동화 인터페이스 프로젝트는 a2apiAgent 자동화 인터페이스를 노출합니다. JavaScript를 통해 switchTab, debug 등의 메서드를 호출할 수 있고, URL, JSON 요청 본문을 지정하여 자동으로 전송할 수 있으며, iframe을 로드하고 자동으로 요청을 전송할 수도 있습니다. 자동화 테스트나 워크플로우에 통합하기 쉽습니다. ## 2단계 계획 교차 기기 동기화(데이터베이스 테이블 또는 파일 가져오기/내보내기)는 설계 단계에서 계획되어 있지만 아직 구현되지 않았습니다. ## 프로젝트 정보 저자는 TommyLemon이며, 프로젝트는 GitHub(open-doubao-ai/OpenDoubao)에 호스팅되어 있습니다. Issue를 통해 기술 문제를 논의하고, Pull Request를 통해 코드를 기여할 수 있습니다.