Initial commit to new repository

docs/TECHNOLOGY_OVERVIEW.md

@@ -0,0 +1,762 @@
+# AX Copilot 기술 및 구현 현황 종합 문서
+
+> **작성일**: 2026-04-03
+> **앱 버전**: v1.8.0 (내부 Phase: v2.3)
+> **프레임워크**: .NET 8.0 WPF (win-x64)
+
+---
+
+## 1. 프로젝트 개요
+
+AX Copilot은 **AI 기반 업무 자동화 데스크톱 앱**으로, 두 가지 핵심 컴포넌트로 구성됩니다:
+
+| 컴포넌트 | 명칭 | 역할 |
+|---------|------|------|
+| **런처** | AX Commander | 키보드 기반 명령 실행 (Alfred/Raycast 대응) |
+| **AI 대화** | AX Agent | LLM 기반 에이전트 코딩/코워크/채팅 (Claude Code/Cursor 대응) |
+
+### 핵심 수치
+
+| 항목 | 수량 |
+|------|------|
+| 에이전트 도구 (IAgentTool) | **64개** |
+| 런처 핸들러 (IHandler) | **44개** |
+| 내장 스킬 (.skill.md) | **40개** |
+| 슬래시 명령 (/command) | **15개** |
+| 대화 프리셋 | **20개** |
+| 테마 | **10개** |
+| 윈도우/뷰 | **27개** (+ 컨트롤 4개) |
+| NuGet 의존성 | **7개** |
+| 훅 이벤트 타입 | **18종** |
+| 훅 실행 모드 | **4종** |
+
+---
+
+## 2. 아키텍처
+
+### 2.1 계층 구조
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  UI 계층 (Views / ViewModels)                            │
+│  · ChatWindow (3-Pane: 사이드바 + 채팅 + 설정 패널)       │
+│  · LauncherWindow (Alfred/Raycast 스타일 명령 팝업)       │
+│  · SettingsWindow, DockBarWindow, CommandPaletteWindow 등 │
+├─────────────────────────────────────────────────────────┤
+│  서비스 계층 (Services)                                   │
+│  · AgentLoopService (에이전트 루프 엔진)                   │
+│  · LlmService (LLM API 통합)                             │
+│  · McpClientService (MCP stdio 프로토콜)                  │
+│  · SkillService, PresetService, HookRunner 등             │
+├─────────────────────────────────────────────────────────┤
+│  도메인 계층 (Tools / Handlers / Models)                  │
+│  · 64개 IAgentTool 구현체                                 │
+│  · 44개 IHandler 구현체 (런처 핸들러)                      │
+│  · AppSettings, ChatModels, McpSettings                  │
+├─────────────────────────────────────────────────────────┤
+│  인프라 계층 (External)                                   │
+│  · LLM API (Ollama / Gemini / Claude)                    │
+│  · MCP 서버 (stdio JSON-RPC 2.0)                         │
+│  · LSP 서버 (Language Server Protocol)                    │
+│  · 파일 시스템, Git, SQLite                               │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 2.2 핵심 디자인 패턴
+
+| 패턴 | 적용 위치 | 설명 |
+|------|----------|------|
+| **Strategy** | IAgentTool, IHookExecutor | 도구/훅 타입별 전략 분리 |
+| **Observer** | AgentEventOccurred, HookRunner | 에이전트 이벤트 발행/구독 |
+| **Factory** | ToolRegistry.CreateDefault() | 도구 인스턴스 생성 중앙화 |
+| **Chain of Responsibility** | PermissionSystem | 권한 규칙 체인 평가 |
+| **Command** | ISlashCommand, SlashCommandRegistry | 슬래시 명령 실행 |
+| **Repository** | HierarchicalMemoryService | 계층적 메모리 CRUD |
+| **Decorator** | IConditionalTool 래핑 | 도구 활성화 조건 동적 평가 |
+
+### 2.3 SOLID 원칙 적용
+
+- **SRP**: 에이전트 도구 1파일 = 1클래스, 카테고리별 폴더 분리
+- **OCP**: `IAgentTool` + `ToolRegistry` — 기존 코드 수정 없이 새 도구 등록
+- **LSP**: 모든 `IAgentTool` 구현체 교환 가능, `ToolResult.Ok()`/`Fail()` 규약 일관
+- **ISP**: `IAgentTool`(Execute/Parameters/Name만), `IConditionalTool`(IsEnabled만) 분리
+- **DIP**: `AgentLoopService` → 인터페이스만 의존, `AgentContext.Settings`로 DI
+
+---
+
+## 3. LLM 통합
+
+### 3.1 지원 서비스
+
+| 서비스 | 프로토콜 | 특징 |
+|--------|---------|------|
+| **Ollama** | REST API (로컬) | 사내망 LLM 서버, 무제한 호출 |
+| **vLLM** | OpenAI 호환 API | 고성능 로컬 추론 서버 |
+| **Google Gemini** | REST API (클라우드) | 무료 티어 지원, 이미지 입력 |
+| **Anthropic Claude** | REST API (클라우드) | SSE 스트리밍, 고급 추론 |
+
+### 3.2 LlmService 핵심 API
+
+```csharp
+// 동기 호출
+Task<string> SendAsync(List<ChatMessage> messages, CancellationToken ct);
+
+// SSE 스트리밍 (실시간 토큰 출력)
+IAsyncEnumerable<string> StreamAsync(List<ChatMessage> messages, CancellationToken ct);
+
+// Function Calling (도구 사용)
+Task<(string Response, List<ContentBlock> ToolCalls)> SendWithToolsAsync(
+    List<ChatMessage> messages, List<ToolDefinition> tools, CancellationToken ct);
+
+// 토큰 사용량 추적
+TokenUsage? LastTokenUsage { get; }
+```
+
+### 3.3 모델 라우팅
+
+- **ModelRouterService**: 작업 유형(코딩/문서/분석)에 따라 최적 모델 자동 선택
+- **FallbackModels**: 주 모델 실패 시 대체 모델 목록 순차 시도
+- **FreeTierMode**: 무료 API 제한 시 자동 지연 (4초 쿨다운)
+
+### 3.4 컨텍스트 관리
+
+| 기능 | 구현 |
+|------|------|
+| **토큰 추정** | TokenEstimator — CJK 가중치 적용 로컬 추정 |
+| **자동 압축** | AutoCompactMonitor — 임계치(80%) 초과 시 자동 컨텍스트 요약 |
+| **컨텍스트 축소** | ContextCondenser — 대화 내 도구 결과/중복 제거 60% 목표 |
+| **출력 예산** | ToolResultSizer — 도구 결과 4,000자 자동 절삭 |
+
+---
+
+## 4. 에이전트 시스템
+
+### 4.1 AgentLoopService (핵심 에이전트 루프)
+
+```
+사용자 입력 → 시스템 프롬프트 조립 → LLM 호출 → 도구 호출 파싱
+    ↓
+도구 실행 (권한 확인 → 훅 실행 → 도구 Execute → 결과 검증)
+    ↓
+결과를 메시지에 추가 → LLM 재호출 (반복)
+    ↓
+종료 조건: 도구 미호출 / 최대 반복 / 사용자 중단
+```
+
+**핵심 파라미터**:
+
+| 상수 | 기본값 | 설명 |
+|------|--------|------|
+| MaxIterations | 25 | 최대 에이전트 반복 횟수 |
+| MaxRetryOnError | 3 | 도구 오류 시 재시도 |
+| MaxTestFixIterations | 5 | 테스트-수정 루프 최대 반복 |
+| AutoCompactThresholdPercent | 80 | 컨텍스트 자동 압축 임계치 |
+| ToolResultTruncateLength | 4,000 | 도구 결과 최대 길이 |
+
+### 4.2 에이전트 도구 (64개)
+
+#### 파일 시스템 (11개)
+| 도구 | 설명 |
+|------|------|
+| FileReadTool | 파일 읽기 (라인 범위 지정) |
+| FileWriteTool | 파일 생성/덮어쓰기 |
+| FileEditTool | 정확한 문자열 치환 편집 |
+| FileInfoTool | 파일 메타데이터 조회 |
+| FileManageTool | 복사/이동/삭제/이름변경 |
+| MultiReadTool | 여러 파일 동시 읽기 |
+| FolderMapTool | 디렉토리 트리 구조 |
+| GlobTool | 파일 패턴 검색 |
+| GrepTool | 정규식 콘텐츠 검색 |
+| FileWatchTool | 파일 변경 감시 |
+| ZipTool | 압축/해제 |
+
+#### 코드 개발 (8개)
+| 도구 | 설명 |
+|------|------|
+| GitTool | Git 명령 실행 (status, diff, commit 등) |
+| LspTool | LSP 분석 (정의/참조/진단) |
+| CodeReviewTool | AI 코드 리뷰 |
+| CodeSearchTool | 의미론적 코드 검색 (TF-IDF) |
+| BuildRunTool | 빌드/테스트 실행 |
+| TestLoopTool | 자동 테스트-수정 반복 |
+| DiffTool | 파일 비교 |
+| DiffPreviewTool | Diff 미리보기 UI |
+
+#### 문서 생성 (9개)
+| 도구 | 설명 |
+|------|------|
+| DocxSkill | Word 문서 생성 (OpenXML) |
+| ExcelSkill | Excel 스프레드시트 생성 |
+| PptxSkill | PowerPoint 프레젠테이션 생성 |
+| HtmlSkill | HTML 페이지 생성 |
+| MarkdownSkill | Markdown 문서 생성 |
+| CsvSkill | CSV 파일 처리 |
+| DocumentPlannerTool | 다중 패스 문서 설계 |
+| DocumentAssemblerTool | 문서 조립/병합 |
+| DocumentReaderTool | 문서 파싱 (PDF/DOCX) |
+
+#### 데이터 처리 (7개)
+| 도구 | 설명 |
+|------|------|
+| JsonTool | JSON 파싱/변환/쿼리 |
+| XmlTool | XML 처리 |
+| SqlTool | SQLite 쿼리 실행 |
+| DataPivotTool | 데이터 피벗/집계 |
+| ChartSkill | 차트 생성 |
+| RegexTool | 정규식 매칭/치환 |
+| FormatConvertTool | 형식 변환 |
+
+#### 에이전트/자동화 (10개)
+| 도구 | 설명 |
+|------|------|
+| SubAgentTool | 서브 에이전트 위임 실행 |
+| PlaybookTool | 워크플로우 자동 실행 |
+| SkillManagerTool | 스킬 관리 (목록/재로드) |
+| MemoryTool | 에이전트 메모리 CRUD |
+| ProjectRuleTool | 프로젝트 규칙 관리 |
+| TaskTrackerTool | 작업 추적/체크리스트 |
+| CheckpointTool | 체크포인트 생성/복원 |
+| SuggestActionsTool | 다음 행동 추천 |
+| UserAskTool | 사용자 질문/확인 |
+| NotifyTool | 사용자 알림 발송 |
+
+#### 유틸리티 (10개)
+| 도구 | 설명 |
+|------|------|
+| HttpTool | HTTP 요청 (GET/POST) |
+| McpTool | MCP 서버 도구 호출 |
+| ProcessTool | 셸 명령 실행 |
+| ClipboardTool | 클립보드 읽기/쓰기 |
+| ImageAnalyzeTool | 이미지 분석 (멀티모달) |
+| Base64Tool | Base64 인코딩/디코딩 |
+| HashTool | 해시값 계산 |
+| EncodingTool | 파일 인코딩 감지/변환 |
+| MathTool | 수학 연산 |
+| DateTimeTool | 날짜/시간 계산 |
+
+#### 기타 (9개)
+| 도구 | 설명 |
+|------|------|
+| DocumentReviewTool | 문서 품질 검토 |
+| DevEnvDetectTool | 개발 환경 감지 |
+| EnvTool | 환경변수 관리 |
+| TemplateRenderTool | Mustache 템플릿 렌더링 |
+| TextSummarizeTool | 텍스트 요약 |
+| SnippetRunnerTool | 코드 스니펫 실행 |
+| OpenExternalTool | 외부 프로그램 열기 |
+| BatchSkill | 대량 파일 처리 |
+| DelegateAgentTool | 특정 작업 위임 |
+
+### 4.3 Plan 모드
+
+| 모드 | 동작 |
+|------|------|
+| **Off** | 즉시 실행 (계획 없이) |
+| **Auto** | 복잡한 작업 시 자동 계획 수립 |
+| **Always** | 모든 작업에 계획 수립 후 사용자 승인 |
+
+Plan 모드에서는 `document_plan` 도구로 단계별 실행 계획을 생성하고, PlanViewerWindow에서 시각화합니다.
+
+### 4.4 권한 시스템 (PermissionSystem)
+
+| 모드 | 설명 |
+|------|------|
+| **Ask** | 모든 파일 작업에 사용자 승인 요청 |
+| **AcceptEdits** | 파일 편집은 자동 승인, bash/위험 도구는 확인 |
+| **Auto** | 모든 도구 자동 실행 |
+| **Deny** | 위험 도구 차단 |
+
+**패턴 기반 규칙**: `Bash(git *)` 형태로 특정 명령만 허용/차단
+**차단 경로**: 시스템 디렉토리, `.env` 등 민감 파일 패턴 차단
+
+---
+
+## 5. 훅 시스템
+
+### 5.1 훅 이벤트 (18종)
+
+| 카테고리 | 이벤트 |
+|---------|--------|
+| **도구 실행** | PreToolUse, PostToolUse, PostToolUseFailure |
+| **세션** | SessionStart, SessionEnd, UserPromptSubmit |
+| **에이전트** | AgentStop, Stop, SubagentStart, SubagentStop |
+| **컨텍스트** | PreCompact, PostCompact, CwdChanged, ConfigChange |
+| **파일** | FileChanged |
+| **스킬** | PreSkillExecute, PostSkillExecute |
+| **권한** | PermissionRequest |
+
+### 5.2 훅 실행 모드 (4종)
+
+| 모드 | 설명 | 예시 |
+|------|------|------|
+| **Command** | 외부 스크립트 실행 | `cmd /c lint.bat` |
+| **Http** | HTTP POST 웹훅 | `https://hooks.slack.com/...` |
+| **Prompt** | LLM 검사 (경량 모델) | "이 코드에 보안 이슈가 있나요?" |
+| **Agent** | 미니 에이전트 루프 | 자동 코드 포맷팅 서브루프 |
+
+### 5.3 훅 출력 기능
+
+| 출력 타입 | 설명 |
+|----------|------|
+| `additionalContext` | LLM 컨텍스트에 추가 정보 주입 |
+| `permissionDecision` | 권한 요청에 대한 자동 판단 |
+| `updatedInput` | 사용자 입력 자동 수정 |
+
+---
+
+## 6. 스킬 시스템
+
+### 6.1 SKILL.md 표준 형식
+
+```markdown
+---
+name: report-writer
+description: 보고서 자동 작성
+tools: [file_write, file_read, grep]
+model: gemini-2.0-flash
+context: fork
+paths: ["docs/**", "reports/**"]
+arguments:
+  topic:
+    description: 보고서 주제
+    required: true
+---
+
+# 시스템 프롬프트
+당신은 보고서 작성 전문가입니다...
+```
+
+### 6.2 스킬 기능
+
+| 기능 | 설명 |
+|------|------|
+| **context:fork** | 서브에이전트로 격리 실행 |
+| **paths: glob** | 특정 경로에서만 자동 활성화 |
+| **model: override** | 스킬별 최적 모델 지정 |
+| **arguments** | 매개변수 치환 (`{{topic}}`) |
+| **inline commands** | 인라인 명령 처리 |
+| **namespacing** | 스킬 이름 충돌 방지 |
+
+### 6.3 내장 스킬 (40개)
+
+| 카테고리 | 스킬명 | 설명 |
+|---------|--------|------|
+| **문서** | report-writer, meeting-minutes, weekly-report, prd-generator, changelog, release-note, email-draft | 보고서/회의록/주간보고/PRD/변경이력/릴리즈노트/이메일 |
+| **코드** | code-scaffold, refactor, gen-test, commit-review, security-audit, perf-audit, dependency-audit | 스캐폴딩/리팩터링/테스트생성/커밋리뷰/보안점검/성능감사/의존성감사 |
+| **데이터** | data-visualize, data-visualize-adv, xlsx-analyzer, csv-to-xlsx, data-convert, yield-analysis, sql-report | 시각화/분석/변환/수율분석/SQL보고서 |
+| **변환** | docx-creator, pptx-creator, markdown-to-doc, json-schema, diagram-generator | 문서생성/프레젠테이션/스키마/다이어그램 |
+| **분석** | paper-review, log-analyze, impact, ocr-extract, image-processor | 논문리뷰/로그분석/영향분석/OCR/이미지처리 |
+| **유틸** | batch-rename, compare, env-setup, regex-helper, translate, api-docs, adr-writer, db-schema | 일괄이름변경/비교/환경설정/정규식/번역/API문서/ADR/DB스키마 |
+
+---
+
+## 7. MCP (Model Context Protocol) 통합
+
+### 7.1 클라이언트 구현
+
+```
+App ──stdio──> MCP 서버 프로세스
+     <──JSON-RPC 2.0──
+```
+
+- **프로토콜**: JSON-RPC 2.0 over stdio
+- **서버 관리**: 프로세스 생명주기 관리 (시작/종료/재연결)
+- **도구 검색**: `tools/list` 요청으로 서버 제공 도구 자동 등록
+- **도구 실행**: `tools/call` 요청으로 원격 도구 호출
+
+### 7.2 SDK 서버 (내장)
+
+AX Copilot 자체가 MCP 서버로 동작하여 외부 MCP 클라이언트에 에이전트 도구를 제공:
+
+| 컴포넌트 | 파일 | 역할 |
+|---------|------|------|
+| SdkProtocol | SdkProtocol.cs | JSON-RPC 프로토콜 정의 |
+| AgentSdkServer | AgentSdkServer.cs | stdio 서버 실행 |
+| AgentTypeRegistry | AgentTypeRegistry.cs | 도구 타입 등록 |
+| SdkHookCallbackHandler | SdkHookCallbackHandler.cs | 훅 이벤트 외부 전달 |
+
+---
+
+## 8. 메모리 시스템
+
+### 8.1 계층적 메모리 (4-Layer)
+
+| 계층 | 범위 | 저장 위치 |
+|------|------|----------|
+| **Global** | 앱 전체 | `%APPDATA%\AxCopilot\memory\global.json` |
+| **Project** | 프로젝트(폴더)별 | `{WorkFolder}\.ax\memory.json` |
+| **Session** | 대화 세션별 | `%APPDATA%\AxCopilot\sessions\{id}\memory.json` |
+| **Agent Type** | 에이전트 타입별 | `%APPDATA%\AxCopilot\memory\{type}.json` |
+
+### 8.2 메모리 도구 (MemoryTool)
+
+| 액션 | 설명 |
+|------|------|
+| `save` | 새 규칙/선호도 저장 |
+| `search` | 키워드로 메모리 검색 |
+| `list` | 모든 메모리 항목 목록 |
+| `delete` | 특정 항목 삭제 |
+
+### 8.3 @include 지시문
+
+프로젝트 규칙 파일에서 외부 파일 참조:
+```markdown
+# AX.md
+@include docs/coding-style.md
+@include docs/api-conventions.md
+```
+- 최대 5단계 중첩 포함
+- 순환 참조 자동 감지/방지
+
+---
+
+## 9. 슬래시 명령 (15개)
+
+| 명령 | 설명 |
+|------|------|
+| `/compact` | 대화 컨텍스트 수동 압축 |
+| `/clear` | 대화 초기화 |
+| `/memory` | 에이전트 메모리 관리 |
+| `/model` | 현재 모델 변경 |
+| `/plan` | Plan 모드 전환 (off/auto/always) |
+| `/commit` | Git 커밋 자동 생성 |
+| `/review` | 코드 리뷰 실행 |
+| `/mcp` | MCP 서버 상태/관리 |
+| `/permissions` | 권한 모드 변경 |
+| `/hooks` | 훅 등록/목록/삭제 |
+| `/config` | 설정값 조회/변경 |
+| `/skills` | 스킬 목록/실행 |
+| `/help` | 명령어 도움말 |
+| `/init` | 프로젝트 초기화 (AX.md 생성) |
+| `/review` | PR/변경사항 리뷰 |
+
+---
+
+## 10. 런처 시스템 (AX Commander)
+
+### 10.1 프리픽스 명령 체계
+
+| 프리픽스 | 기능 | 핸들러 |
+|---------|------|--------|
+| `!` | AI 대화 시작 | ChatHandler |
+| `?` | 웹 검색 | WebSearchHandler |
+| `>` | 시스템 명령 | SystemCommandHandler |
+| `=` | 계산기 | CalculatorHandler |
+| `#` | 색상 변환 | ColorHandler |
+| `@` | 퀵링크 | QuickLinkHandler |
+| `$` | 환경변수 | EnvHandler |
+| `/` | 즐겨찾기 | FavoriteHandler |
+| `%` | 프로세스 관리 | ProcessHandler |
+| `:` | 이모지 | EmojiHandler |
+| `+` | 노트 | NoteHandler |
+| `-` | 일괄 텍스트 처리 | BatchTextHandler |
+| `~` | 별칭 | AliasHandler |
+| `*` | 서비스 관리 | ServiceHandler |
+| `^` | 클립보드 이력 | ClipboardHistoryHandler |
+| `` ` `` | 코드 스니펫 | SnippetHandler |
+
+### 10.2 주요 기능
+
+| 기능 | 설명 |
+|------|------|
+| **퍼지 검색** | 앱/파일/설정 퍼지 매칭 |
+| **파일 인덱싱** | 로컬 파일 TF-IDF 인덱스 |
+| **클립보드 이력** | DPAPI 암호화 저장, 원본 이미지 품질 |
+| **독 바** | 하단 퀵 액세스 바 |
+| **셸 통합** | Windows Explorer 우클릭 메뉴 |
+| **커맨드 팔레트** | VS Code 스타일 Ctrl+Shift+P |
+| **AI 스니펫** | 프롬프트 기반 자동 텍스트 생성 |
+
+---
+
+## 11. UI/UX 시스템
+
+### 11.1 AX Agent 3-Pane 레이아웃 (Claude.ai 스타일)
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ [좌측 사이드바]  │  [메인 채팅 영역]       │ [우측 설정 패널]  │
+│ 260px           │  가변                    │ 300px (토글)     │
+│                 │                          │                  │
+│ Chat│Cowork│Code│  세션 헤더 바             │  ⚙ 모델 & 서비스 │
+│ ─────────────── │  (모델▾ Plan▾ 권한▾)      │  에이전트 동작    │
+│ 프리셋 목록      │                          │  탭 전용 설정     │
+│ ─────────────── │  메시지 스트림             │  도구 관리        │
+│ [+ 새 대화]      │  (마크다운 렌더링)         │  MCP 서버        │
+│ ─────────────── │                          │  프리셋            │
+│ 대화 이력        │  입력 영역                │  고급              │
+│ (날짜별 그룹)     │  (@멘션 /스킬 📎)         │                  │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### 11.2 테마 시스템 (10종)
+
+| 테마 | 스타일 |
+|------|--------|
+| Dark | 기본 다크 테마 |
+| OLED | 순흑 배경 AMOLED |
+| Nord | 북극빛 색상 |
+| Monokai | 개발자 인기 테마 |
+| Catppuccin | 파스텔 다크 |
+| Codex | OpenAI Codex 스타일 |
+| Alfred | Alfred 앱 스타일 |
+| Alfred Light | Alfred 라이트 변형 |
+| Light | 기본 라이트 테마 |
+| Sepia | 따뜻한 세피아 톤 |
+
+### 11.3 커스텀 UI 규칙
+
+- **기본 컨트롤 사용 금지**: ContextMenu → 커스텀 Popup, MessageBox → CustomMessageBox
+- **테마 리소스 필수**: `ThemeResourceHelper.Primary(this)` 패턴으로 색상 조회
+- **PopupMenuHelper**: 팝업 메뉴 생성 통합 헬퍼
+- **ToggleSwitch 스타일**: 기본 CheckBox 대신 좌우 슬라이드 토글
+- **아이콘**: Segoe MDL2 Assets 글리프 + 기능별 색상
+
+### 11.4 애니메이션
+
+| 동작 | 구현 | 시간 |
+|------|------|------|
+| 사이드바 접기/펼치기 | Width 260→48px | 180ms |
+| 우측 패널 슬라이드 | TranslateTransform X | 200ms |
+| 탭 전환 | Opacity + TranslateY | 120ms |
+| 메시지 등장 | Opacity + TranslateY | 120ms |
+| 스트리밍 커서 | Opacity 깜빡임 | 500ms |
+| 도구 블록 펼치기 | Height 애니메이션 | 150ms |
+
+---
+
+## 12. 보안 시스템
+
+### 12.1 데이터 보호
+
+| 항목 | 방법 |
+|------|------|
+| API 키 | AES-256-GCM + DPAPI 이중 암호화 |
+| 클립보드 이력 | DPAPI 암호화 저장 |
+| 가이드 문서 | AES-256-CBC 암호화 (.enc) |
+| 설정 파일 | 로컬 저장 (`%APPDATA%\AxCopilot\`) |
+
+### 12.2 AI 기능 제어
+
+| 설정 | 기본값 | 설명 |
+|------|--------|------|
+| `AiEnabled` | `false` | AI 기능 전체 차단/허용 (비밀번호 보호) |
+| `InternalModeEnabled` | `true` | 사내 모드 — 외부 인터넷 차단 |
+
+### 12.3 감사 로그 (AuditLogService)
+
+모든 에이전트 도구 실행, 파일 변경, 권한 결정을 JSON 형식으로 기록:
+```json
+{
+  "timestamp": "2026-04-03T14:30:00",
+  "event": "tool_execution",
+  "tool": "file_write",
+  "path": "src/main.cs",
+  "permission": "auto",
+  "result": "success"
+}
+```
+
+---
+
+## 13. 세션 관리
+
+### 13.1 세션 기능
+
+| 기능 | 설명 |
+|------|------|
+| **자동 저장** | 대화별 자동 저장/복원 |
+| **포크** | 현재 세션 분기하여 별도 대화 |
+| **태그** | 세션에 라벨 태그 |
+| **카테고리** | 작업 유형별 자동 분류 |
+| **고정** | 중요 대화 상단 고정 |
+| **검색** | 대화 이력 전문 검색 |
+
+### 13.2 멀티에이전트
+
+| 기능 | 구현 |
+|------|------|
+| **서브에이전트** | SubAgentTool — 독립 컨텍스트에서 작업 위임 |
+| **Worktree 격리** | Git worktree 기반 서브에이전트 독립 작업 |
+| **백그라운드 실행** | BackgroundAgentService — 비동기 실행 + 완료 알림 |
+| **코디네이터** | 계획 수립 → 서브에이전트 분배 → 결과 병합 |
+
+---
+
+## 14. 외부 의존성
+
+### 14.1 NuGet 패키지 (7개)
+
+| 패키지 | 버전 | 용도 | 크기 |
+|--------|------|------|------|
+| DocumentFormat.OpenXml | 3.2.0 | Office 문서 생성 (DOCX/XLSX/PPTX) | ~5MB |
+| Markdig | 0.37.0 | Markdown 파싱/렌더링 | ~1MB |
+| Microsoft.Data.Sqlite | 8.0.0 | SQLite 로컬 DB | ~2MB |
+| Microsoft.Web.WebView2 | 1.0.2903.40 | 내장 브라우저 | ~3MB |
+| System.Security.Cryptography.ProtectedData | 8.0.0 | DPAPI 암호화 | <1MB |
+| System.ServiceProcess.ServiceController | 8.0.1 | Windows 서비스 관리 | <1MB |
+| UglyToad.PdfPig | 1.7.0-custom-5 | PDF 파싱/텍스트 추출 | ~2MB |
+
+### 14.2 시스템 의존성
+
+| 의존성 | 용도 |
+|--------|------|
+| .NET 8.0 Runtime | 앱 실행 (self-contained) |
+| WebView2 Runtime | HTML 렌더링, 가이드 뷰어 |
+| Segoe MDL2 Assets | 시스템 아이콘 폰트 |
+| Windows 10+ | WPF, DPAPI, P/Invoke |
+
+---
+
+## 15. 코드 품질 리팩터링 이력 (Phase 33~36)
+
+### 15.1 Phase 33 — AgentLoopService 구조 개선
+
+| 작업 | 내용 |
+|------|------|
+| 매직 넘버 상수화 | 16개 `Defaults` 상수 클래스 |
+| RunAsync 분해 | `ProcessSingleToolCallAsync` 250줄 추출 (27% 감소) |
+| 중복 제거 | AutoCompactMonitor + ContextCondenser 통합 |
+| 레이스 컨디션 | ActiveTab 스냅샷 패턴 적용 |
+| 에러 핸들링 | bare catch → `catch (Exception)` + 주석 |
+
+### 15.2 Phase 34 — ChatWindow God Class 분해
+
+| 작업 | 내용 |
+|------|------|
+| ThemeResourceHelper | `TryFindResource` 190건 → 헬퍼 메서드 |
+| FontFamily 캐싱 | 54건 `new FontFamily()` → 정적 필드 |
+| PopupMenuHelper | 팝업 생성 패턴 통합 헬퍼 |
+| RunAgentLoopAsync | Cowork/Code 70줄 중복 → 40줄 통합 |
+
+### 15.3 Phase 35 — 코드 품질 심층 정리
+
+| 작업 | 영향 범위 |
+|------|----------|
+| bare catch 전량 정리 | 109개 파일 |
+| ColorConverter 헬퍼 | 81건 → `HexBrush()`/`HexColor()` |
+| `_settings.Settings.Llm` 캐싱 | 92건 → `Llm` 프로퍼티 |
+| AgentContext.Settings DI | 11개 도구 서비스 로케이터 제거 |
+
+### 15.4 Phase 36 — 서비스 로케이터 제거 + PopupMenuHelper 적용
+
+| 작업 | 영향 범위 |
+|------|----------|
+| `Application.Current as App` 일원화 | 15개 파일, 39건 → `CurrentApp` |
+| PopupMenuHelper 실제 적용 | 4개 팝업 메서드, 169줄 감소 |
+
+---
+
+## 16. 빌드 및 배포
+
+### 16.1 빌드 구성
+
+```xml
+<PropertyGroup>
+  <OutputType>WinExe</OutputType>
+  <TargetFramework>net8.0-windows</TargetFramework>
+  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
+  <SelfContained>true</SelfContained>
+  <PublishSingleFile>true</PublishSingleFile>
+</PropertyGroup>
+```
+
+### 16.2 배포 체계
+
+| 항목 | 설명 |
+|------|------|
+| **인스톨러** | AxCopilot.Installer (WinForms 기반) |
+| **업데이트** | 수동 인스톨러 실행 (자동 업데이트 없음) |
+| **배포 크기** | 목표 150MB 이하 (현재 ~80MB) |
+| **데이터** | `%APPDATA%\AxCopilot\` 로컬 저장 |
+
+### 16.3 가이드 문서 체계
+
+```
+개발자 가이드 (.htm) → 암호화 → guide_dev.enc → 앱 내장 뷰어
+                     ↓
+사용자 가이드 (.htm) → 암호화 → guide_user.enc → 앱 내장 뷰어
+(버전이력 제거)
+```
+
+---
+
+## 17. 프로젝트 파일 구조
+
+```
+E:\AX Copilot\
+├── docs/
+│   ├── AGENT_ROADMAP.md          # AI 에이전트 로드맵
+│   ├── LAUNCHER_ROADMAP.md       # 런처 로드맵
+│   ├── NEXT_ROADMAP.md           # 종합 차기 계획
+│   ├── DEVELOPMENT.md            # 개발 문서
+│   └── TECHNOLOGY_OVERVIEW.md    # ← 이 문서
+├── src/
+│   ├── AxCopilot/                # 메인 앱
+│   │   ├── Services/             # 서비스 계층 (43+ 파일)
+│   │   │   └── Agent/            # 에이전트 서비스
+│   │   │       ├── 64 tool files # IAgentTool 구현체
+│   │   │       ├── SlashCommands/ # 15개 슬래시 명령
+│   │   │       └── Sdk/          # MCP SDK 서버
+│   │   ├── Handlers/             # 런처 핸들러 (44개)
+│   │   ├── Views/                # UI 윈도우 (27개)
+│   │   │   └── Controls/        # 재사용 컨트롤 (4개)
+│   │   ├── ViewModels/           # MVVM ViewModel
+│   │   ├── Models/               # 데이터 모델
+│   │   ├── Themes/               # 10개 테마 XAML
+│   │   ├── Assets/               # 정적 리소스
+│   │   │   └── Presets/          # 20개 프리셋
+│   │   ├── skills/               # 40개 내장 스킬
+│   │   └── Core/                 # 핵심 유틸리티
+│   ├── AxCopilot.Installer/      # 인스톨러 프로젝트
+│   ├── AxCopilot.SDK/            # 외부 SDK
+│   └── AxCopilot.Tests/          # 단위 테스트
+└── CLAUDE.md                     # AI 개발 지시사항
+```
+
+---
+
+## 18. 완료된 Phase 전체 목록
+
+### AI 에이전트 (Phase 2.5 ~ 36)
+
+| Phase | 제목 | 버전 | 상태 |
+|-------|------|------|------|
+| 2.5-7 | 에이전트 루프, 마크다운, Code 탭 | v1.1-1.2.1 | ✅ |
+| 7.5 | 레인보우 글로우, 테마 개선 | v1.2.2 | ✅ |
+| 8 | MCP, 모델 폴백, 분기, 토큰 관리 | v1.5.0 | ✅ |
+| 9 | LSP, 병렬 에이전트, 코드 검색, 테스트 루프 | v1.5.0 | ✅ |
+| 10 | 모델 라우터, 메모리, 훅, 멀티모달 | v1.5.0 | ✅ |
+| 11 | 스킬 시스템, 코드 리뷰, 드래그 앤 드롭 | v1.5.0 | ✅ |
+| 12 | 도구 관리 UI, SKILL.md, 스킬 에디터/갤러리 | v1.5.x | ✅ |
+| 15 | 문서 엔진, PPT, 피벗, 16 내장 스킬 | v1.6.0 | ✅ |
+| 16 | Plan 모드, 프로젝트 규칙, 병렬 실행 | v1.7.0 | ✅ |
+| 16.5 | 검증 강제, 후처리 검증, 피드백 학습 | v1.7.1 | ✅ |
+| 16.8 | 컨텍스트 압축, 이력 복원, 속도 개선 | v1.7.2 | ✅ |
+| 17-UI | 3-Pane 채팅 화면 재설계 | v1.8.0 | ✅ |
+| 17-A~G | Reflexion, 태스크 상태, 훅, 스킬, 메모리, 권한, Diff | v1.8.0 | ✅ |
+| 18-A~C | 멀티에이전트, 리플레이, 플러그인 갤러리 | v2.0 | ✅ |
+| 19~19-G | CC 동등성 달성 (메모리, 권한, 훅, 스킬, 세션) | v2.1 | ✅ |
+| 22~29 | 슬래시 명령 14개, 최종 통합 검증 | v2.1 | ✅ |
+| 30 | 아키텍처 정제, 계층적 메모리 | v2.1 | ✅ |
+| 31 | SDK 제어 프로토콜 (JSON 스트리밍) | v2.2 | ✅ |
+| 32 | 3-Pane Claude.ai UI 구조 | v2.3 | ✅ |
+| 33 | AgentLoopService 코드 품질 리팩터링 | v2.3 | ✅ |
+| 34 | ChatWindow God Class 분해 | v2.3 | ✅ |
+| 35 | 코드 품질 심층 정리 (bare catch, 색상, DI) | v2.3 | ✅ |
+| 36 | 서비스 로케이터 제거 + PopupMenuHelper | v2.3 | ✅ |
+
+### 런처 (Phase L1 ~ L2+)
+
+| Phase | 제목 | 버전 | 상태 |
+|-------|------|------|------|
+| L1 | 44 핸들러, 퍼지 검색, 10 테마, 플러그인 | v1.5.0 | ✅ |
+| L1+ | 셸 확장, 스토리지, 독 바 | v1.5.0 | ✅ |
+| L2 | 클립보드 강화, UX 개선 | v1.5.3 | ✅ |
+| L2+ | 독 바 정렬, 가이드 뷰어, 정보 업데이트 | v1.5.3 | ✅ |
+
+---
+
+> **Claude Code 동등성**: 37/37 핵심 기능 구현 완료
+> **코드 품질 리팩터링**: Phase 33~36, 4차 반복 완료
+> **빌드 상태**: 경고 0, 오류 0