Korean Grammar Assistant is an Obsidian community plugin for checking Korean spelling, grammar, and writing style inside your vault. It combines Bareun.ai's Korean language analysis with optional AI providers such as OpenAI, Anthropic Claude, Google Gemini, and Ollama to help writers review Korean text, compare correction suggestions, and apply changes without leaving Obsidian.

The plugin is designed for people who write Korean notes, drafts, study material, documentation, or professional text in Obsidian. It supports two editing workflows: a popup review mode for focused correction sessions and a beta inline mode for reviewing suggestions directly in the editor. Detected issues are shown with clear visual states, keyboard navigation, mobile-friendly controls, and optional AI reasoning so users can decide whether to apply a correction, keep the original wording, ignore a term, or make a custom edit.

English Overview

Key Features

• Korean spelling and grammar checking powered by Bareun.ai.
• Optional AI-assisted review with OpenAI, Anthropic Claude, Google Gemini, or local Ollama models.
• Popup review mode for focused proofreading and batch correction.
• Beta inline mode for reviewing and applying corrections directly inside the editor.
• Multiple correction suggestions for each detected issue.
• Five-state correction workflow: original error, corrected text, ignored exception, keep original, and user-edited text.
• Keyboard navigation for fast review with Tab, Shift+Tab, arrow keys, Enter, Escape, and editing shortcuts.
• Mobile-friendly layout with touch controls and responsive popup sizing.
• Morphological analysis support for more accurate Korean word-boundary handling.
• Token estimation and warning controls for optional AI requests.

Network And Privacy

Korean Grammar Assistant sends selected text to Bareun.ai when you run the standard Korean grammar check. If you enable AI-assisted review, the plugin can also send correction context to the AI provider that you explicitly configure in settings. API keys are stored locally in your Obsidian vault configuration and are not sent anywhere except to the selected service provider during requests.

The plugin does not include telemetry, analytics, tracking, or a remote plugin account system. It does not upload your whole vault. Network requests are only made when grammar checking or optional AI analysis is triggered, and provider usage can be controlled from the plugin settings.

Requirements

1. A Bareun.ai API key is required for the primary Korean spelling and grammar analysis.
2. An AI provider key or local Ollama endpoint is optional and only needed for AI-assisted suggestions.
3. Obsidian 1.4.0 or newer is required.

Installation

When installed from the Obsidian Community Plugins directory, enable the plugin from Settings, then open the Korean Grammar Assistant settings tab and enter your Bareun.ai API key. Optional AI provider settings can be configured in the same settings tab.

For manual installation, download main.js, manifest.json, and styles.css from the latest GitHub release and place them in:

<your vault>/.obsidian/plugins/korean-grammar-assistant/

Then restart Obsidian or reload community plugins and enable Korean Grammar Assistant.

Basic Usage

1. Select Korean text in the editor.
2. Run Korean Grammar Assistant from the ribbon icon or command palette.
3. Review detected issues in the popup or inline editor.
4. Choose a correction, keep the original text, add an exception, or edit the text manually.
5. Apply the final changes back to the note.

AI-Assisted Usage

After a standard grammar check, you can run AI analysis to ask the configured provider to evaluate the detected issues in context. AI suggestions can include confidence scores, reasoning, exception handling, and recommended corrections. Users remain in control of the final text and must apply changes explicitly.

한국어 맞춤법 검사기

Bareun.ai와 다양한 AI 제공자를 활용한 Obsidian용 고급 한국어 맞춤법 및 문법 검사 플러그인입니다. 현대적인 UI/UX와 함께 포괄적인 한국어 텍스트 교정 기능을 제공합니다.

🆕 NEW: 인라인 모드 베타 (v0.2.6)

📝 인라인 편집 모드가 드디어 출시되었습니다!

⚡ 인라인 모드 핵심 기능

• 🎯 클릭 기반 교정: 텍스트 선택 후 오류 감지 및 제안 목록 표시
• 🔄 인라인 편집: 문서를 벗어나지 않고 바로 교정 작업 수행
• ⌨️ 키보드 네비게이션: Tab/Shift+Tab으로 오류 간 빠른 이동
• 📱 모바일 최적화: 터치 제스처 및 모바일 키보드 완벽 지원
• 🎨 5색 상태 시스템: 오류(빨강) → 수정(초록) → 예외처리(파랑) → 원본유지(주황) → 사용자편집(보라)

🏗️ 모듈화된 아키텍처

인라인 모드는 완전히 새로운 모듈화 아키텍처로 구축되었습니다:

• 15개 전문화된 모듈: 3,500+ 라인 → 평균 200-400라인 모듈로 분리
• 완전한 책임 분리: 데코레이션, 이벤트, 상태, AI 통합, UI 컴포넌트별 독립 관리
• 확장 가능한 구조: 새 기능 추가 시 기존 코드 영향 최소화
• 타입 안전성: TypeScript 컴파일 오류 0개 달성

📱 플랫폼별 최적화

• 데스크톱: 마우스 호버 + 키보드 단축키 + 우클릭 컨텍스트
• 모바일: 터치 제스처 + 스와이프 + 롱프레스 + 44px 터치 영역

🚀 성능 개선

• 지연 로딩: 필요할 때만 컴포넌트 초기화
• 메모리 효율성: 자동 리소스 정리 및 이벤트 관리
• 실시간 반응: 디바운스 기반 상태 변경 처리 (150ms)

⚠️ 베타 알림: 인라인 모드는 현재 베타 단계입니다. 피드백과 버그 리포트를 환영합니다!

✨ 주요 기능

핵심 기능

• 고급 문법 및 맞춤법 검사: Bareun.ai의 최첨단 한국어 처리 기술 활용
• AI 기반 교정: OpenAI, Anthropic (Claude), Google (Gemini), Ollama와 통합된 지능형 상황 인식 제안
• 2가지 편집 모드: 🆕 인라인 모드 (실시간 편집) + 팝업 모드 (집중 편집)
• 3가지 직관적 편집 방법: ⌨️ CMD+E 키보드 단축키, 🖱️ 미리보기 우클릭, 📝 오류 카드 좌클릭
• 5단계 스마트 토글: 오류 → 수정 → 예외처리 → 원본유지 → 사용자편집 → 오류 순환
• 실시간 미리보기: 색상으로 구분된 상태와 함께 교정 사항 즉시 확인
• 다중 제안 지원: 감지된 각 오류에 대한 여러 교정 옵션 제공

현대적인 UI/UX

• 🆕 인라인 편집: 문서 내에서 직접 실시간 교정 (베타)
• 스마트 페이지네이션: 화면 공간과 콘텐츠에 따른 동적 페이지 크기 조정
• 모바일 최적화: iPhone 노치를 위한 Safe Area 지원과 터치 친화적 인터페이스
• 반응형 디자인: 다양한 화면 크기에 완벽하게 적응
• 5가지 색상 코딩: 오류(빨강), 교정(초록), 예외처리(파랑), 원본유지(주황), 사용자편집(보라)
• 대형 모달 인터페이스: 편안한 편집을 위한 넓은 작업 공간

AI 전용 기능

• 다중 AI 제공자: OpenAI, Anthropic, Google 또는 로컬 Ollama 인스턴스 중 선택
• 지능형 분석: AI가 전체 맥락을 고려하여 최적의 교정 제공
• 신뢰도 점수: 각 AI 제안에 신뢰도 점수(0-100%) 제공
• 상세한 추론: AI가 특정 교정을 선택한 이유 이해
• 자동 예외 처리: AI가 고유명사, URL, 기술 용어를 식별하고 보존
• 사용자 편집 인식: AI가 사용자의 직접 편집 내용을 실시간으로 이해하고 존중
• 형태소 정보 통합: 품사 정보를 AI 분석에 제공하여 더 정확한 문법 교정
• 토큰 효율성: 스마트 컨텍스트 축소로 비용 절감 (최대 70% 토큰 절약)
• 원클릭 적용: AI 제안을 검토하고 한 번의 클릭으로 적용

🚀 빠른 시작

사전 요구사항

1. Bareun.ai 계정: 기본 문법 검사를 위해 https://bareun.ai/에서 가입
2. API 키: Bareun.ai 대시보드에서 개인 API 키 획득
3. (선택사항) AI 제공자 계정: AI 기능을 위해 OpenAI, Anthropic, Google의 API 키 또는 실행 중인 Ollama 인스턴스 필요

🔐 네트워크 및 개인정보 공개

• Bareun.ai API: 맞춤법 분석을 위해 선택한 텍스트를 Bareun.ai 서버로 전송합니다. 응답 데이터는 로컬에서만 사용되며 저장되지 않습니다.
• AI 제공자 (선택): OpenAI, Anthropic, Google Gemini, Ollama 중 선택한 서비스로 오류 문맥을 전송하여 제안을 받습니다. 어떤 제공자를 사용할지는 설정에서 직접 제어할 수 있습니다.
• 추가 데이터 수집 없음: 플러그인은 텔레메트리를 전송하지 않으며, 사용자의 노트나 자격 증명은 Obsidian 볼트 밖으로 저장하지 않습니다.
• 로컬 제어: 모든 API 키는 사용자의 장치에만 보관되며, 네트워크 사용은 설정에서 언제든지 비활성화할 수 있습니다.

설치

방법 1: 수동 설치 (권장)

1. 이 저장소를 다운로드하거나 클론합니다.
2. npm install && npm run build를 실행합니다.
3. main.js, manifest.json, styles.css를 Obsidian 볼트의 .obsidian/plugins/korean-grammar-assistant/ 폴더에 복사합니다.
4. Obsidian 설정에서 플러그인을 활성화합니다.

방법 2: BRAT 플러그인

1. Obsidian에서 BRAT 플러그인을 설치합니다.
2. BRAT에 이 저장소의 URL을 추가합니다.
3. Korean Grammar Assistant를 설치하고 활성화합니다.

설정

1. 플러그인 활성화: 설정 → 커뮤니티 플러그인 → Korean Grammar Assistant → 활성화로 이동
2. API 설정 구성: 설정 → Korean Grammar Assistant로 이동
   • Bareun.ai API 키 (필수): 개인 Bareun.ai API 키
   • AI 제공자 (선택사항): 선호하는 AI 제공자를 선택하고 해당 API 키 또는 엔드포인트 입력

📱 사용법

🆕 인라인 모드 사용법 (베타)

1. 설정 활성화: 플러그인 설정에서 "인라인 모드" 활성화
2. 텍스트 선택: 교정하려는 텍스트 선택 후 분석 실행
3. 빠른 교정: 오류가 감지되면 클릭하여 제안 목록 확인
4. 키보드 네비게이션: Tab/Shift+Tab으로 오류 간 이동
5. 상태 토글: 클릭으로 5단계 상태 순환 (오류→수정→예외→원본→편집)

기본 워크플로우 (팝업 모드)

1. 텍스트 선택: 검사하려는 한국어 텍스트를 하이라이트합니다.
2. 검사기 실행: 리본 아이콘을 클릭하거나 명령 팔레트 → "맞춤법 검사"를 사용합니다.
3. 오류 검토: 미리보기 창에서 감지된 문제점을 확인합니다.
4. 3가지 편집 방법:
   • ⌨️ 키보드: CMD+E로 현재 포커스된 오류 편집
   • 🖱️ 마우스: 미리보기에서 오류 텍스트 우클릭하여 편집
   • 📝 카드: 하단 오류 상세 카드를 좌클릭하여 편집
5. 5단계 토글: 각 오류를 클릭하여 오류 → 수정 → 예외처리 → 원본유지 → 사용자편집 순환
6. 키보드 네비게이션: Tab으로 오류 간 이동, ←/→로 수정 제안 순환, Enter로 적용
7. 완료: "적용"을 클릭하여 문서에 변경 사항을 저장합니다.

AI 기반 워크플로우

1. 기본 검사 수행: 위의 기본 워크플로우를 따릅니다.
2. 사용자 편집 (선택사항): 원하는 오류를 직접 편집하여 AI에게 의도를 전달합니다.
3. AI 분석 실행: 팝업 헤더의 "🤖 AI 분석" 버튼을 클릭합니다.
4. AI 제안 검토: AI가 사용자 편집 내용을 고려하여 최적의 교정을 자동 선택합니다.
5. 신뢰도 확인: 각 제안의 신뢰도 점수(0-100%)와 상세한 추론을 검토합니다.
6. 적용: "적용"을 클릭하여 AI 기반 교정을 저장합니다.

🎨 인터페이스 가이드

5가지 색상 상태 시스템

• 🔴 빨강 (오류): 감지된 오류가 있는 원본 텍스트
• 🟢 초록 (수정): AI/시스템 제안 수정안이 적용된 상태
• 🔵 파랑 (예외처리): 향후 맞춤법 검사에서 제외될 텍스트 (고유명사, 전문용어 등)
• 🟠 주황 (원본유지): 이번에만 유지, 다음 검사 시 다시 확인될 텍스트
• 🟣 보라 (사용자편집): 사용자가 CMD+E/우클릭/카드클릭으로 직접 편집한 텍스트

편집 방법

1. ⌨️ CMD+E: 현재 포커스된 오류를 키보드로 빠르게 편집
2. 🖱️ 우클릭: 미리보기에서 오류 텍스트를 우클릭하여 즉시 편집 모드
3. 📝 카드 클릭: 하단 오류 상세 카드를 좌클릭하여 체계적으로 편집

⌨️ 키보드 네비게이션

플러그인은 완전한 키보드 지원을 제공하여 마우스 없이도 효율적으로 작업할 수 있습니다:

기본 네비게이션

• Tab: 다음 오류로 이동
• Shift+Tab: 이전 오류로 이동
• ←/→: 현재 오류의 수정 제안 순환 (앞/뒤)
• Enter: 현재 선택된 수정사항 적용
• Escape: 팝업 닫기

편집 및 AI 기능

• CMD+E: 현재 포커스된 오류 편집 모드 진입
• Shift+CMD+A: AI 분석 실행
• CMD+Shift+E: 오류 상세 영역 펼침/접힘

일괄 작업

• CMD+Shift+→: 모든 오류를 다음 제안으로 일괄 변경
• CMD+Shift+←: 모든 오류를 이전 제안으로 일괄 변경

페이지 네비게이션 (긴 텍스트)

• ↑: 이전 페이지
• ↓: 다음 페이지

💡 키보드 힌트: 데스크톱에서 팝업 열 때 자동으로 키보드 단축키 가이드가 표시됩니다.

🤖 AI 특화 기능

사용자 의도 인식

AI는 사용자가 직접 편집한 내용을 실시간으로 파악하고 다음과 같이 처리합니다:

• 🟣 보라색 상태 인식: 사용자가 편집한 텍스트를 우선적으로 존중
• 문맥 기반 판단: 사용자 편집이 문법적으로 올바르면 그대로 유지 권장
• 의도 고려: 명백한 오타가 있어도 사용자 의도를 고려하여 신중하게 판단

5단계 토글 시스템

🔴 오류 → 🟢 수정안 → 🔵 예외처리 → 🟠 원본유지 → 🟣 사용자편집 → 🔴 오류

• 각 단계를 클릭하여 순환하거나 역방향(Shift+클릭)으로 이동
• AI가 모든 상태를 인식하여 최적의 제안 제공
• 사용자의 선택 패턴을 학습하여 더 정확한 분석

🔬 고급 분석 시스템

맞춤법 검사 플로우

텍스트 입력 → Bareun.ai 맞춤법 분석 → 형태소 분석 → 오류 개선 → AI 분석 → 최종 제안

형태소 분석의 역할

• 정확한 품사 구분: 명사/동사/형용사별 맞춤형 교정 제안
• 중복 오류 제거: 동일 형태소 내 겹치는 오류 통합
• 문법적 컨텍스트: 단어 경계와 품사 정보로 더 정확한 분석
• 오류 위치 최적화: 형태소 경계 기반 정확한 오류 범위 지정

AI 토큰 최적화 전략

스마트 컨텍스트 윈도우

• 기본 모드: 앞뒤 100자 컨텍스트 제공
• 형태소 모드: 앞뒤 30자로 축소 (품사 정보로 보완)
• 토큰 절감: 평균 70토큰 절약 (복수 오류 시)

배치 처리

• 단일 API 호출: 여러 오류를 한 번에 분석
• 비용 효율성: API 호출 수 최소화
• 병렬 처리: 대용량 텍스트 동시 분석

토큰 사용량 모니터링

• 실시간 추정: 실제 프롬프트 기반 정확한 토큰 계산
• 사용자 제어: 설정 가능한 토큰 임계값
• 투명한 비용: 예상 API 비용 사전 표시

🛠️ 기술 아키텍처

🆕 모듈화된 아키텍처 (v0.2.6)

인라인 모드 시스템

• 핵심 모듈: InlineModeCore, ErrorProcessor, AIIntegration
• 데코레이션 시스템: DecorationManager, ErrorDecoration, AIDecoration, FocusDecoration
• 이벤트 시스템: EventManager, ClickHandler, HoverHandler, KeyboardHandler, TouchHandler
• 상태 관리: InlineState, ErrorState, SelectionState
• UI 컴포넌트: ErrorTooltip, ErrorWidget, AIWidget

팝업 모드 시스템 (완전 리팩토링 완료)

• 6개 핵심 시스템: 상태관리, 페이지네이션, 키보드, AI통합, 성능, 이벤트
• 21개 전문화된 모듈: 3,309라인 → 평균 200-600라인
• 완전한 책임 분리: 각 시스템의 명확한 단일 책임 및 독립성
• 플랫폼 추상화: 데스크톱/모바일 차이를 아키텍처 레벨에서 완전 분리

프론트엔드

• 언어: TypeScript with strict mode
• UI/UX: CSS3, Obsidian API, 반응형 디자인
• 상태 관리: 5단계 토글 시스템, 실시간 상태 동기화
• 키보드 네비게이션: Obsidian Scope API 활용한 완전한 키보드 지원

백엔드 & API 통합

• 한국어 처리: Bareun.ai API (맞춤법 검사 + 형태소 분석)
• AI 분석: OpenAI, Anthropic (Claude), Google (Gemini), Ollama
• 멀티 제공자: 동적 AI 클라이언트 팩토리 패턴
• API 최적화: 요청 배칭, 타임아웃 관리, 재시도 로직

고급 분석 시스템

🧠 3단계 분석 파이프라인

1. 맞춤법 분석: Bareun.ai 기본 오류 감지
2. 형태소 분석: 품사 정보 기반 오류 개선 및 중복 제거
3. AI 분석: 문맥과 사용자 의도를 고려한 최적화

📊 형태소 기반 최적화

• 중복 오류 그룹화: 동일 형태소 단위의 오류 통합
• 품사 정보 활용: 명사, 동사, 형용사별 맞춤형 교정
• 패턴 매칭: 형태소 경계 기반 정확한 오류 위치 특정

🤖 AI 토큰 최적화

• 컨텍스트 윈도우 동적 조정: 형태소 정보 있을 때 100→30토큰으로 축소
• 배치 처리: 여러 오류를 단일 API 호출로 처리
• 토큰 사용량 예측: 실제 프롬프트 기반 정확한 비용 추정
• 임계값 경고 시스템: 설정 가능한 토큰 한계와 사용자 확인

🔧 성능 최적화

• 메모리 캐싱: LRU 방식 100개 항목 캐시 (형태소 분석 결과)
• API 재사용: 중복 분석 방지, 기존 분석 데이터 활용
• 비동기 처리: Promise 기반 논블로킹 분석
• 오류 복구: 네트워크 실패 시 점진적 폴백

📋 최신 업데이트 (v0.2.6 - 2025.07.29)

🆕 인라인 모드 베타 출시

• 실시간 인라인 편집: 문서 내에서 직접 교정 작업 수행
• 모듈화 아키텍처: 3,500+ 라인을 15개 전문 모듈로 완전 분리
• 플랫폼별 최적화: 데스크톱(호버+키보드) vs 모바일(터치+제스처)
• 성능 개선: 지연 로딩, 메모리 효율성, 실시간 반응성

🏗️ CorrectionPopup 완전 리팩토링 완료

• 7개 Phase 완성: 상태관리, 페이지네이션, 키보드, AI통합, 성능, 이벤트, UI
• 21개 모듈 분리: 3,309라인을 전문화된 모듈로 완전 분리
• TypeScript 완전 지원: 컴파일 오류 0개 달성
• 접근성 강화: 18개 키보드 단축키 + 완전한 터치 지원

🔧 시스템 안정성 개선

• 토큰 계산 시스템: 정확한 비용 예측 및 경고
• 성능 최적화: PerformanceOptimizer로 메모리 및 DOM 최적화
• 에러 핸들링: 우아한 에러 복구 및 사용자 피드백

📋 최신 업데이트 (v0.2.4 - 2025.07.24)

🔧 프로덕션 최적화

• 지능형 로그 시스템: DEBUG/INFO/WARN/ERROR 레벨 체계적 분류
• 성능 모니터링: 개발용 로그 파일 분리 및 .gitignore 최적화
• 메모리 최적화: 불필요한 디버깅 메시지 제거

🤖 AI 분석 강화

• 5단계 상태 인식: AI가 🔴🟢🔵🟠🟣 모든 UI 상태를 실시간 이해
• 사용자 편집 존중: CMD+E/우클릭/카드클릭 편집 내용을 AI가 우선 고려
• 실시간 상태 전달: 각 오류의 현재 상태를 AI 분석에 포함

📚 문서화 완성

• 17개 키보드 단축키: 완전한 키보드 기반 워크플로우 지원
• 3단계 분석 파이프라인: 맞춤법→형태소→AI 과정 투명화
• 토큰 최적화 공개: 최대 70% 절약 전략 상세 문서화

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출하거나 이슈를 열어주세요.

📄 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• Bareun.ai: 훌륭한 한국어 처리 API 제공
• Obsidian 커뮤니티: 영감과 피드백 제공