Gemini API 연동 개발

이 문서는 DokuWiki와 Google Gemini API를 연동한 플러그인 개발에 대한 상세한 설명입니다.

• 편집기 툴바 기능: DokuWiki 편집기 툴바에 두 개의 전용 AI 버튼을 추가하여 사용자 접근성을 높였습니다.
  • 파란색 버튼: 전체 편집기 내용을 기반으로 새로운 초안을 생성합니다.
  • 녹색 버튼: 선택된 텍스트를 사용자의 지시에 따라 수정합니다.
• 반응형 디자인: 다양한 기기 (데스크톱, 태블릿, 모바일)에서 최적의 사용 경험을 제공하기 위해 반응형 웹 디자인 원칙을 적용했습니다.
• 시각적 색상 구분: 기능별로 명확한 색상 구분을 통해 사용자가 각 버튼의 역할을 직관적으로 이해할 수 있도록 돕습니다.

• 메인 플러그인 클래스 (action.php): 모든 DokuWiki 이벤트 처리와 핵심 로직을 담당하는 플러그인의 중심 파일입니다. 사용자 요청을 처리하고 Gemini API와 통신합니다.
• AJAX 이벤트 핸들러 등록: 비동기 통신을 위해 DokuWiki의 AJAX 시스템에 사용자 인터페이스에서 발생하는 특정 이벤트를 처리하는 핸들러를 등록합니다.
• API 키 관리 및 보안: Gemini API 키는 DokuWiki의 보안 설정 관리자를 통해 안전하게 저장 및 관리되며, 하드코딩을 방지하여 보안 취약점을 최소화합니다.
• 사용량 제한 및 모니터링: 과도한 API 호출을 방지하고 비용을 효율적으로 관리하기 위해 호출 횟수를 모니터링하고 제한하는 로직이 구현되어 있습니다.

• 사용자 인터페이스 로직 (script.js): DokuWiki 편집기와 상호작용하며, 사용자의 텍스트 선택, 버튼 클릭 등 모든 UI 관련 동작을 처리합니다.
• 텍스트 선택 및 편집기 조작: 사용자가 DokuWiki 편집기에서 텍스트를 선택하거나 수정할 때, 해당 텍스트를 가져오고 AI 응답을 편집기에 다시 삽입하는 기능을 수행합니다.
• AJAX 통신 및 오류 처리: 백엔드와의 비동기 통신을 담당하며, 네트워크 문제나 API 오류 발생 시 사용자에게 적절한 피드백을 제공합니다.
• 사용자 피드백 제공: 로딩 스피너, 성공/실패 메시지 등 시각적인 피드백을 통해 사용자가 현재 AI 작업의 상태를 명확히 알 수 있도록 합니다.

• 전체 편집기 내용 기반: 현재 DokuWiki 편집기에 작성된 모든 내용을 문맥으로 활용하여, 사용자가 의도하는 바에 맞는 상세하고 일관성 있는 초안을 생성합니다. 이는 긴 문서 작성 시 매우 유용합니다.
• DokuWiki 문법 규칙 엄격 준수: 생성되는 모든 텍스트는 DokuWiki의 표준 문법 규칙(예: 제목, 목록, 링크, 강조 등)을 철저히 준수하여 별도의 수정 없이 바로 사용할 수 있도록 합니다.
• 상세하고 구조적인 문서 생성: 단순히 텍스트를 나열하는 것을 넘어, 적절한 제목, 소제목, 목록 등을 활용하여 논리적이고 가독성 높은 문서 구조를 자동으로 생성합니다.
• 한국어 출력 보장: 다국어 지원 환경에서 특히 중요하며, AI가 생성하는 모든 내용이 정확하고 자연스러운 한국어로 제공되도록 최적화되어 있습니다.

• 선택된 텍스트만 수정: 사용자가 편집기에서 특정 부분을 드래그하여 선택하면, AI는 해당 선택 영역만을 대상으로 수정 작업을 수행하여 정교한 편집이 가능합니다.
• 사용자 지시사항 기반 수정: “더 간결하게”, “전문적인 어조로 변경”, “예시 추가” 등 사용자의 구체적인 지시사항을 받아들여 텍스트를 맞춤형으로 수정합니다.
• 원본 DokuWiki 문법 보존: 수정 과정에서도 기존 DokuWiki 문법(예: 볼드체, 이탤릭체, 내부 링크 등)을 손상시키지 않고 유지하여 문서의 무결성을 보장합니다.
• 실시간 편집기 업데이트: AJAX 통신을 통해 AI 응답을 실시간으로 DokuWiki 편집기에 반영하여 사용자가 즉각적으로 결과를 확인하고 추가 작업을 진행할 수 있습니다.

• DokuWiki 설정 관리자를 통한 안전한 키 저장: API 키는 DokuWiki의 관리자 설정 페이지를 통해 입력되며, 시스템 파일에 하드코딩되지 않고 안전하게 암호화되어 저장됩니다. 이는 보안 취약점을 줄이고 유지보수를 용이하게 합니다.
• 하드코딩 방지: 소스 코드 내에 민감한 API 키를 직접 포함하지 않음으로써, 코드 유출 시 발생할 수 있는 보안 사고를 미연에 방지합니다.
• 관리자 권한으로만 접근 가능: API 키 설정 및 변경은 DokuWiki 관리자 권한을 가진 사용자에게만 허용되어, 무단 접근 및 변경을 막습니다.

• 분당 10회 호출 제한: 짧은 시간 내 과도한 API 요청이 발생하는 것을 방지하여, 서비스 부하를 줄이고 갑작스러운 비용 증가를 막습니다.
• 일일 500회 호출 제한: 하루 동안의 총 호출 횟수를 제한하여, 장기적인 관점에서 API 사용 비용을 효율적으로 관리하고 오남용을 방지합니다.
• 파일 기반 사용량 추적: 각 사용자의 API 호출 기록은 서버의 특정 로그 파일에 저장되어 실시간으로 추적되며, 이를 통해 사용량 제한을 적용합니다.
• 자동 제한 및 사용자 알림: 설정된 제한을 초과할 경우, API 호출이 자동으로 차단되며 사용자에게는 친절한 알림 메시지(예: “API 사용량 제한 초과”)를 통해 상황을 안내합니다.

• 최신 모델 사용으로 성능 최적화: Google의 최신 Gemini 2.5 Flash 모델을 사용하여, 최적의 성능과 정확성을 제공합니다. 이는 빠른 응답 속도와 우수한 텍스트 생성 능력을 보장합니다.
• 1,048,576 토큰 입력 한도: 매우 긴 DokuWiki 문서(약 32,000단어 이상)도 한 번에 처리할 수 있을 만큼 방대한 입력 토큰 한도를 제공하여, 광범위한 문맥 이해를 가능하게 합니다.
• 65,536 토큰 출력 한도: 단일 요청으로 약 2,000단어 이상의 상세한 응답을 받을 수 있는 충분한 출력 토큰 한도를 제공하여, 포괄적인 문서 초안 생성이 가능합니다.
• 빠른 응답 속도: Flash 모델의 최적화된 설계 덕분에, 사용자 요청에 대한 AI의 응답 속도가 매우 빨라 효율적인 작업 흐름을 지원합니다.

모델의 응답 특성을 제어하기 위한 핵심 매개변수 설정입니다.

generationConfig: {
    temperature: 0.7,        // 창의성 조절 (0.0~1.0): 값이 높을수록 더 다양하고 창의적인 응답을 생성합니다.
    topP: 1.0,              // 다양성 조절 (0.0~1.0): 다음 토큰으로 선택될 확률이 높은 토큰들의 누적 확률을 제한하여 응답의 다양성을 조절합니다.
    topK: 32,               // 토큰 선택 범위 (정수): 다음 토큰을 선택할 때 고려할 가장 높은 확률을 가진 토큰의 수를 제한합니다.
    maxOutputTokens: 8192    // 최대 출력 길이 (정수): AI가 생성할 수 있는 최대 토큰 수를 지정하여 응답 길이를 제어합니다.
}

AI가 DokuWiki 문서를 정확하게 생성하고 수정할 수 있도록 지시하는 핵심 문법 규칙입니다.

• 제목: DokuWiki의 가독성 및 일관성을 위해 섹션은 Level 3(`===`), Level 4(`====`), Level 5(`=====`)만 사용하도록 지시합니다. Level 6(`======`)은 최상위 문서 제목에만 사용됩니다.
• 목록: 들여쓰기는 정확히 두 칸(` *` 또는 ` -`)을 사용하여 계층 구조를 명확히 표현하도록 합니다.
• 코드: 인라인 코드는 `code` 형식으로, 여러 줄의 코드 블록은 `

  ...

  ` 태그를 사용하도록 지시하며, 백틱(`` ` ``) 사용은 엄격히 금지합니다.

• 구분선: 섹션 간의 명확한 구분을 위해 정확히 네 개의 하이픈(`—-`)으로 구성된 수평선을 사용하도록 합니다.

AI에게 DokuWiki 문서 초안 생성을 지시하는 기본 프롬프트입니다. 이 프롬프트는 AI가 DokuWiki 전문가로서 포괄적이고 상세한 문서를 생성하도록 유도합니다.

You are an expert assistant for DokuWiki. 
Your task is to expand this raw text into a 
**comprehensive and detailed** DokuWiki document draft. 
The draft must have an introduction, a body with 
several sections (using headlines), and a conclusion.

플러그인 사용 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.

• cURL 함수 없음: PHP 환경에 cURL 확장이 설치되지 않은 경우 발생합니다. `sudo apt-get install php-curl` (Debian/Ubuntu) 또는 해당 OS/PHP 버전에 맞는 명령어로 설치해야 합니다.
• API 키 미설정: DokuWiki 관리자 설정에서 Gemini API 키가 올바르게 입력되지 않은 경우입니다. 관리 → 환경 설정 → 플러그인 설정에서 키를 입력하고 저장해야 합니다.
• 사용량 초과: 설정된 API 호출 제한(분당/일일)을 초과한 경우입니다. 잠시 기다리거나, API 할당량을 확인하고 필요시 증량을 고려해야 합니다.
• 네트워크 오류: DokuWiki 서버가 Google Gemini API 서버와 통신할 수 없는 경우 발생합니다. 서버의 인터넷 연결 상태, 방화벽 설정 등을 확인해야 합니다.

플러그인 문제 발생 시 원인을 파악하기 위한 디버깅 절차입니다.

• 브라우저 개발자 도구 확인: 웹 브라우저의 개발자 도구(F12)를 열어 네트워크 탭에서 AI 요청 및 응답의 상태 코드, 페이로드 등을 확인하여 통신 문제를 파악합니다.
• DokuWiki 오류 로그 확인: DokuWiki의 `data/log/debug.log` 파일에 기록되는 오류 메시지를 확인하여 백엔드에서 발생하는 PHP 오류나 플러그인 내부 오류를 분석합니다.
• API 응답 원본 확인 (임시 디버그 모드): 플러그인 설정에 임시 디버그 모드를 활성화하여 Gemini API로부터 받은 원본 응답을 로그에 출력하도록 설정할 수 있습니다. 이를 통해 API의 실제 응답 내용을 직접 확인하여 문제를 진단합니다.

• 비동기 AJAX 호출: AI 응답을 기다리는 동안 사용자 인터페이스가 멈추지 않도록 비동기 AJAX 호출을 사용하여 쾌적한 사용자 경험을 제공합니다.
• 사용량 제한: API 호출 횟수를 제한함으로써 불필요한 비용 발생을 방지하고, API 서버에 대한 과도한 부하를 줄여 안정적인 서비스를 유지합니다.
• 반응형 디자인: 다양한 화면 크기와 해상도에 자동으로 맞춰지는 반응형 디자인을 적용하여, 데스크톱부터 모바일 기기까지 모든 환경에서 일관되고 최적화된 사용성을 보장합니다.
• 캐시 활용: 자주 사용하는 데이터나 API 응답 중 재사용 가능한 부분을 캐싱하여, 불필요한 API 호출을 줄이고 서버 부하를 감소시켜 전체적인 응답 속도를 향상시킵니다.

• 개발 문서 메인
• Gemini API 설정
• 플러그인 개발 가이드
• 메인 페이지