adongwanai/learn-workbuddy

해결하는 문제

데스크톱 AI 어시스턴트를 구축하는 것은 명령줄 에이전트보다 훨씬 어렵습니다. 도구를 호출하는 간단한 루프는 터미널에서 잘 작동하지만, 데스크톱 앱은 세션을 넘나들며 계속 실행되어야 하고, 컨텍스트 창을 초과하지 않고 방대한 도구 출력을 관리해야 하며, 장기 메모리를 안전하게 저장해야 하고, 에이전트가 백도어가 되지 않도록 권한을 제어해야 하며, 수많은 움직이는 부품을 분리해야 합니다. 이 프로젝트는 이러한 문제를 24개의 구조화된 레슨으로 변환하며, 각 레슨은 작동하는 Python 코드와 다이어그램을 사용하여 정확히 하나의 메커니즘을 추가합니다.

작동 방식

이 프로젝트는 프로덕션 소스 코드가 아닌 교육용 청사진입니다. 데스크톱 에이전트를 UI, 에이전트 추론, 도구 실행, 확장 시스템, 메모리 시스템, 안전 거버넌스의 6개 계층으로 분해합니다. 각 레슨(s01~s24)은 이전 레슨을 기반으로 하며, 기본 에이전트 루프, 도구 디스패치, 권한 후크부터 Electron 셸, 사이드카 서버, 세션 관리, 모델 라우팅, JSONL 트랜스크립트, 작업 공간/사용자/클라우드 메모리, 출력 외부화, 프롬프트 어셈블리, 스킬, MCP 커넥터, 전문가, 시각화, SQLite, 자동화, 해시 체인 감사 샌드박스에 이르기까지 한 번에 하나의 핵심 메커니즘을 추가합니다.

Mini WorkBuddy라는 최소 참조 구현이 포함되어 있으며 Python 표준 라이브러리만 사용하여 구축되었으므로 에이전트 루프, 권한 가드가 있는 도구, JSONL 스토리지, 외부화된 출력, 추가 전용 감사 로그, REST/ACP 유사 서버, DeepSeek, Anthropic, OpenAI 및 OpenAI 호환 게이트웨이를 단일 ToolCall/ModelTurn 인터페이스로 정규화하는 공급자 어댑터 등 전체 요청 경로를 검사할 수 있습니다.

각 장의 code.py를 --demo 플래그로 실행하면 API 키 없이 많은 데모를 완전히 오프라인으로 실행할 수 있습니다. 실제 모델 레슨의 경우 DEEPSEEK_API_KEY(또는 Anthropic/OpenAI 키)를 입력하고 모델/도구 JSONL 추적을 기록하는 대화형 교육 CLI 또는 통합 평가 모드를 실행할 수 있습니다. scripts/verify.py는 구문, 테스트, 오프라인 데모, 문서 및 클린룸 준수를 확인합니다.

대상 독자

기본 CLI 에이전트(관련 learn-claude-code 프로젝트 등)를 이미 이해하고 데스크톱 제품 엔지니어링을 더 깊이 배우고 싶은 개발자를 위한 것입니다. 장기 실행 프로세스 설계, 메모리 및 컨텍스트 관리, 다중 에이전트 협업 처리, 안전 강화, 여러 모델 공급자와의 통합을 배울 수 있습니다. 또한 최소한의 종속성으로 실습 중심의 장별 접근 방식을 선호하는 교육자와 자기 주도 학습자에게도 적합합니다.

하이라이트

• 실행 가능한 Python 코드와 28개의 다이어그램을 갖춘 24개 장. 각 레슨은 정확히 하나의 메커니즘을 추가
• UI, 추론, 도구, 확장, 메모리, 안전의 책임 경계를 보여주는 6계층 아키텍처
• 공급자 어댑터 계층을 통한 다중 공급자 지원(DeepSeek, Anthropic, OpenAI, OpenAI 호환 게이트웨이). 루프는 안정적으로 유지되고 모델은 교체 가능
• 표준 라이브러리 Mini WorkBuddy 하네스를 포함한 대부분의 예제에 대한 완전 오프라인 데모. API 키 없이 전체 파이프라인을 실행하고 검사 가능
• 메모리 시스템을 5개 계층(작업 공간, 사용자, 원격 프로필, 트랜스크립트, 도구 결과 스왑)으로 세분화. 핵심 아이디어: 컨텍스트 창은 RAM, JSONL, SQLite, 메모리 파일, 도구 결과는 디스크
• 클린룸 보장: 원본 교육 코드와 공개된 아키텍처 관찰만 포함하며 WorkBuddy의 비공개 소스 코드, 키 또는 개인 프롬프트는 절대 포함하지 않음
• 메모리 복원력, 증거 기반 RAG, 검색 라우팅, 모든 레슨에서 공급자를 비교할 수 있는 모델 벤치마크와 같은 고급 평가 예제 포함