# AX Commander

Windows 전용 시맨틱 런처 & 워크스페이스 매니저

> Alfred (macOS)에서 영감을 받아 Windows 환경에 최적화된 키보드 중심 생산성 도구입니다.

개발 참고: Claw Code 동등성 작업 추적 문서  
`docs/claw-code-parity-plan.md`

---

## 주요 기능 (프리픽스 치트시트)

| 프리픽스 | 기능 | 예시 |
|----------|------|------|
| *(없음)* | 앱·파일 퍼지 검색 + 앱 단축키 | `vscode`, `크롬`, `ㅅㄷ` (초성) |
| `=` | **계산기** — 수식 즉시 계산, Enter로 결과 복사 | `= sqrt(16)`, `= 2^10`, `= sin(30)` |
| `/` | **시스템 명령** — 잠금·절전·재시작·종료 | `/lock`, `/sleep`, `/shutdown` |
| `;` | **텍스트 스니펫** — 키워드로 저장된 텍스트 붙여넣기 | `;addr`, `;sig` |
| `#` | **클립보드 히스토리** — 복사 이력 검색 & 재사용 | `# hello`, `#` |
| `@` | URL 단축키 | `@gh` → GitHub 열기 |
| `~` | 폴더 단축키 | `~dl` → Downloads 폴더 |
| `>` | 명령 실행 / 배치 단축키 | `>git status` |
| `$` | 클립보드 텍스트 변환 (12종) | `$json`, `$b64e`, `$upper`, `$ts` |
| `!` | 워크스페이스 저장·복원 | `!save work`, `!restore work` |

### Alfred 대비 기능 현황

| 기능 | Alfred | AX Commander |
|------|--------|-----------------|
| 앱 퍼지 검색 | ✅ | ✅ |
| 한국어 초성 검색 | ❌ | ✅ |
| 파일 검색 | ✅ | ✅ (exe/lnk/bat/ps1) |
| 계산기 | ✅ | ✅ `=` 프리픽스 |
| 시스템 명령 | ✅ | ✅ `/` 프리픽스 (7가지) |
| 텍스트 스니펫 | ✅ | ✅ `;` 프리픽스 + 변수 치환 |
| 클립보드 히스토리 | ✅ | ✅ `#` 프리픽스 |
| 클립보드 변환 | ❌ | ✅ `$` 프리픽스 (12종) |
| URL 단축키 | ✅ | ✅ `@` 프리픽스 |
| 폴더 단축키 | ✅ | ✅ `~` 프리픽스 |
| 터미널 명령 | ✅ | ✅ `>` 프리픽스 |
| 워크스페이스 관리 | ❌ | ✅ `!` 프리픽스 |
| 플러그인 SDK | ✅ | ✅ (`IActionHandler`) |
| HTTP API 스킬 | ✅ | ✅ (`.skill.json`) |
| 테마 커스터마이징 | ❌ | ✅ (7종 프리셋 + 완전 커스텀) |
| 설정 UI | ✅ | ✅ (7탭 전체 GUI 설정) |

---

## 설치 및 빌드

### 요구 사항

- **OS**: Windows 10 20H2 이상 (Windows 11 권장)
- **.NET**: 8.0 Runtime (Self-contained 빌드 시 불필요)

### 빌드

```bash
# 소스 클론
git clone https://github.com/your/oledic.git
cd "oledic/AX Commander"

# 개발 실행
dotnet run --project src/AxCommander

# Release 단일 파일 빌드 (self-contained)
dotnet publish src/AxCommander -c Release -r win-x64 --self-contained
```

### 릴리즈 게이트 실행

릴리즈 전에는 아래 스크립트로 빌드/패리티/리플레이/전체 테스트를 일괄 검증합니다.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1
```

빠른 점검만 필요할 때는 전체 테스트를 생략할 수 있습니다.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1 -SkipFullTest
```

### 데이터 경로

| 용도 | 경로 |
|------|------|
| 설정 파일 | `%APPDATA%\AxCommander\settings.json` |
| 로그 | `%APPDATA%\AxCommander\logs\app-YYYY-MM-DD.log` |
| 스킬 파일 | `%APPDATA%\AxCommander\skills\*.skill.json` |
| 크래시 덤프 | `%APPDATA%\AxCommander\crashes\` |

---

## 사용법

### 키보드 단축키

| 동작 | 단축키 |
|------|--------|
| 런처 열기 / 닫기 | `Alt+Space` |
| 설정 열기 | `Ctrl+,` |
| 다음 항목 선택 | `↓` |
| 이전 항목 선택 | `↑` |
| 실행 | `Enter` |
| 자동완성 (선택 항목 제목 채우기) | `Tab` |
| 닫기 | `Esc` |

### 계산기 예시

```
= 1 + 2 * 3          → 7
= sqrt(144)          → 12
= 2^10               → 1024
= sin(30)            → 0.5     (도 단위)
= log(1000)          → 3
= pi * 5^2           → 78.5398...
= 0xFF + 16          → 271
= round(3.14159, 2)  → 3.14
```

### 스니펫 변수

스니펫 내용에서 아래 변수를 사용할 수 있습니다:

| 변수 | 치환 값 | 예시 |
|------|---------|------|
| `{date}` | 오늘 날짜 | `2026-03-23` |
| `{time}` | 현재 시각 | `14:30:00` |
| `{datetime}` | 날짜+시각 | `2026-03-23 14:30:00` |
| `{year}` | 연도 | `2026` |
| `{month}` | 월 (2자리) | `03` |
| `{day}` | 일 (2자리) | `23` |

---

## 플러그인 개발

### DLL 플러그인

`AxCommander.SDK`를 참조하여 `IActionHandler` 인터페이스를 구현합니다.

```csharp
using AxCommander.SDK;

public class MyHandler : IActionHandler
{
    public string? Prefix => "?";   // 트리거 프리픽스 (null이면 prefix 없는 핸들러)
    public PluginMetadata Metadata => new("MyPlugin", "설명", Version: "1.0");

    public async Task<IEnumerable<LauncherItem>> GetItemsAsync(string query, CancellationToken ct)
    {
        return [ new LauncherItem("제목", "부제목", null, myData, Symbol: "\uE721") ];
    }

    public Task ExecuteAsync(LauncherItem item, CancellationToken ct)
    {
        // item.Data로 전달한 데이터를 꺼내 실행 로직 작성
        return Task.CompletedTask;
    }
}
```

빌드한 DLL 경로를 `settings.json`의 `plugins` 배열에 추가:

```json
{
  "plugins": [
    { "path": "C:\\MyPlugins\\MyPlugin.dll", "enabled": true }
  ]
}
```

### JSON 스킬 (코드 없이 HTTP API 연동)

`%APPDATA%\AxCommander\skills\` 에 `.skill.json` 파일을 놓으면 됩니다.

```json
{
  "id": "github-search",
  "name": "GitHub 검색",
  "prefix": "@gh",
  "credential": { "type": "bearer_token", "credentialKey": "github_token" },
  "request": {
    "method": "GET",
    "url": "https://api.github.com/search/repositories?q={{INPUT}}&per_page=10"
  },
  "response": {
    "resultsPath": "items",
    "titleField": "full_name",
    "subtitleField": "description",
    "actionUrl": "html_url"
  },
  "cache": 30
}
```

---

## 테마

7가지 내장 테마와 완전 커스텀 테마를 지원합니다.

| 테마 | 특징 |
|------|------|
| `system` | Windows 다크/라이트 모드 자동 감지 |
| `dark` | 딥 네이비 다크 (기본) |
| `light` | 클린 화이트 라이트 |
| `oled` | 순수 블랙 (OLED 절전) |
| `nord` | Arctic 컬러 팔레트 |
| `monokai` | Sublime Text 스타일 |
| `catppuccin` | Mocha 따뜻한 파스텔 |
| `sepia` | 황갈색 아날로그 감성 |
| `custom` | 14개 색상 완전 커스터마이징 |

설정 UI(`Ctrl+,` → 테마 탭)에서 클릭 한 번으로 즉시 미리보기 적용.

---

## 변경 이력

### v0.7.3 — AX Agent 권한 코어 재구성 + 입력 계층 정리

업데이트: 2026-04-04 12:11 (KST)

| 분류 | 내용 |
|------|------|
| 권한 코어 재구성 | `Default → AcceptEdits → Plan → BypassPermissions → DontAsk → Deny` 체계로 정규화하고, 기존 `Ask/Auto` 값은 호환 alias로 유지 |
| 규칙 해석 순서 정리 | 권한 판정을 `deny 규칙 → allow/override 규칙 → 글로벌 모드 → 기본 Ask` 순서로 재구성 |
| 도구 권한 클래스 분리 | `file_write/file_edit/file_manage`와 `process/build_run/test_loop/snippet_runner/spawn_agent` 계열을 분리해 `AcceptEdits`와 `Plan`의 실제 동작 차이를 반영 |
| AX Agent 권한 UI 반영 | 권한 팝업, 상단 배너, slash 명령 결과가 새 권한 모드 의미를 표시하도록 정리 |
| AX Agent 설정창 복구 | `AgentSettingsWindow`의 깨진 한글 문자열을 정리하고 운영 모드, 계획 모드, 추론 강도, 폴더 데이터 활용 라벨을 현재 AX 표현 체계로 복구 |
| 권한 용어 통일 | 권한 팝업과 인라인 설정에서 `계획 중심`, `완전 자동`, `질문 없이 진행` 등 한국어 표기를 일관되게 사용하도록 정리 |
| 권한 UI·로직 결합 정리 | `claw-code` 권한 팝업 흐름에 맞춰 코어 4개(`권한 요청/편집 자동 승인/계획 모드/권한 건너뛰기`)를 기본 선택 순서로 정렬하고, 토글 순환도 동일 축으로 단순화 |
| 슬래시 팔레트 단순화 | `/` 팝업의 기본 선택을 첫 항목으로 바꾸고, 즐겨찾기 버튼/배지 UI를 제거해 `아이콘+명령+설명` 중심의 단순 리스트 탐색으로 정리 |
| 컴포저 패널 축소 | 하단 인라인 설정을 `Fast/추론/계획/권한` 중심으로 축소하고, 스킬/브라우저/MCP 버튼은 숨겨 입력 중심 UX로 정리 |
| 모델/프리셋 바 컴팩트화 | 입력창 상단 바를 더 촘촘한 크기로 정리하고, 긴 모델명은 자동 말줄임 처리해 레이아웃이 흔들리지 않도록 보강 |
| 좌측 패널 타이포 정돈 | 사이드바 헤더/메뉴/대화 리스트의 폰트 크기와 여백을 줄여 밀도를 맞추고, 대화 카드 제목·시간·상태 배지의 크기를 통일해 시인성을 개선 |
| 메시지 버블 정돈 | 사용자/어시스턴트 버블의 여백·폰트·타임스탬프·액션 버튼 크기를 줄이고 좌우 마진을 대칭화해 대화 로그 가독성과 정렬감을 개선 |
| 에이전트 이벤트 표시방식 정리 | 실행 배너의 과도한 펼침 UI를 제거하고 요약 길이를 제한해 한눈에 상태를 읽도록 단순화, 권한/계획/실행 라벨을 한국어 기준으로 통일 |
| 도구 결과 카드 단순화 | 파일 경로 배너를 `파일명 + 디렉터리` 2단 구조로 정리하고, 빠른 작업 버튼을 아이콘 전용(프리뷰/열기/폴더/복사)으로 축소해 시각적 복잡도를 낮춤 |
| 작업 요약 팝업 정돈 | 팝업 헤더/필터 밀도를 낮추고 `전체·권한·대기·도구·서브·훅` 중심으로 재정렬해 스크롤 시 탐색 피로를 줄임 |
| 권한 이력 카드 재구성 | 권한 카드/이력을 `현재 모드·설명·기본/예외` + `시간·도구·결과` 구조로 단순화하고, 권한 액션 버튼도 최신 용어(`활용하지 않음/권한 요청/편집 자동 승인/계획 모드/권한 건너뛰기`)로 통일 |
| 최근 실행 카드 압축 | `최근 에이전트 실행` 카드에서 상세 로그/파일 나열과 분기 액션을 줄이고 `요약+카운트+타임라인` 중심으로 정리해 표시 밀도와 스캔 속도를 개선 |
| 작업 카드 버튼 스타일 통일 | 작업 요약/권한/훅/백그라운드 카드 버튼을 공통 생성 함수로 통일해 패딩·폰트·테두리·색상 톤을 일관화하고 카드 간 버튼 밀도 차이를 제거 |
| 카드 타이포 계층 정렬 | 작업/훅/백그라운드 카드의 제목·본문 글자 크기와 굵기를 통일하고 `PrimaryText/SecondaryText` 기반으로 대비를 맞춰 카드 간 시각 리듬을 정리 |
| 카드 아이콘 규칙 통일 | 작업 종류별 아이콘/색을 공통 매핑으로 통일하고, 작업·훅·백그라운드 카드 헤더에 아이콘을 배치해 상태 인지가 한눈에 되도록 정리 |
| 권한 팝업 선택 강조 개선 | 권한 모드 리스트에서 활성 항목에 배경/테두리/체크 아이콘을 적용하고 설명 줄간격·아이콘 정렬을 조정해 선택 상태와 읽기 흐름을 명확화 |
| 권한 예외/거부 영역 압축 | 권한 팝업의 `도구별 예외`와 `최근 권한 거부` 블록을 아이콘 헤더+간결 라벨 체계로 정리하고 버튼 명칭을 권한 용어(`권한 요청/편집 자동 승인/활용하지 않음/예외 해제`)로 통일 |
| 권한 팝업 섹션 접힘/펼침 | 기본 화면은 `핵심 권한 모드`만 노출하고 `현재 권한 요약/도구별 예외/최근 권한 거부/고급 모드`는 접힘 섹션으로 전환해 codex/claude식 간결 흐름으로 정리 |
| 권한 팝업 섹션 상태 기억 | 접힘 섹션의 마지막 펼침 상태를 `settings.dat`에 저장해 팝업 재오픈 시 사용자 마지막 선택을 복원 |
| 슬래시 팔레트 그룹 상태 기억 | `/` 팔레트에 `명령/스킬` 접힘 헤더를 추가하고 마지막 펼침 상태를 저장해 재오픈 시 복원, Up/Down 이동도 펼쳐진 그룹 항목만 순회하도록 보정 |
| 슬래시 최근 사용 상단 고정 | `/` 팔레트의 `명령/스킬` 그룹 내부 항목을 최근 사용(MRU) 기준으로 상단 정렬하고 `최근` 배지를 표시, 선택 스크롤도 실제 렌더 항목 기준으로 정확히 보정 |
| 슬래시 핀 고정 결합 | `/` 팔레트 항목 우측에 핀 토글을 추가하고 정렬 우선순위를 `핀 > 최근 > 이름`으로 적용해 자주 쓰는 명령을 고정 유지 |
| AX Agent 기본 활성화 | `ai_enabled` 기본값을 활성화로 변경하고 설정 로드 정규화 단계에서 비활성 값이 들어와도 자동으로 활성화되도록 보정 |
| 업데이트 안내 메시지 제거 | 앱 시작 시 설정 마이그레이션 후 표시되던 `설정 업데이트` 메시지박스를 제거해 업데이트 설치 직후 팝업 노출을 중단 |
| 슬래시 핀/최근 개수 설정 연동 | AX Agent 설정창에서 `슬래시 핀 최대 개수`, `슬래시 최근 최대 개수`를 조절할 수 있도록 추가하고 런타임(MRU/핀 정렬) 제한에 즉시 반영 |
| 슬래시 개수 설정 QA 완료 | 핀/최근 상한 적용 후 `/` 팔레트 정렬과 실행 경로를 회귀 점검하고 `ChatWindowSlashPolicyTests` 39개를 통과하여 동작 안정성을 확인 |
| 슬래시 퀵관리/권한 키보드 보강 | `/` 팔레트 헤더에 `정리/전체 접기·펼치기`를 추가하고, 권한 팝업에 `Tab/Enter/Esc` 중심 키보드 조작(항목 선택·섹션 토글·닫기)을 보강 |
| 슬래시/권한 접근성 완성도 보강 | `/` 팔레트에 `모두 접힘` 안내와 섹션 상태 라벨을 추가하고, 권한 팝업 오픈 시 첫 포커스 이동/Enter·Space 선택/ESC 닫기를 보강해 키보드 사용성을 개선 |
| 설정 즉시 반영 가시성 보강 | AX Agent 설정의 슬래시 핀/최근 상한 항목에 `저장 후 즉시 반영` 안내를 추가해 조작 결과를 명확히 인지하도록 정리 |
| 회귀 패키지 통과 | 전체 테스트 436개 통과로 슬래시/권한/설정 저장 경로 변경 후 회귀 안정성 확보 |
| 슬래시 탐색 입력 확장 | `/` 팝업에서 휠/방향키 외에 `PageUp/PageDown/Home/End` 이동을 추가하고 고해상도 휠 델타를 단계 이동으로 보정해 스크롤 사용성을 개선 |
| 모델 빠른설정 단일 라인 강화 | 입력창 상단 모델 버튼을 AX Agent 내부 빠른 설정 토글로 전환하고, 모델/프리셋 버튼 높이와 패딩을 정돈해 Codex/Claude형 단일 라인 흐름에 맞춤 |
| UI 점검 체크리스트 추가 | 내부/사외 모드 포함 UI 회귀 점검 문서를 `docs/UI_UX_CHECKLIST.md`로 추가해 시나리오 기반 검증 기준을 명문화 |
| Slash palette 상태 분리 시작 | `ChatWindow`에 몰려 있던 slash 상태를 `SlashPaletteState`로 분리해 이후 Codex/Claude형 composer 개편 기반 마련 |
| 런처 이미지 미리보기 추가 | `#` 클립보드 이미지 항목에서 `Shift+Enter`로 전용 미리보기 창을 열고, 줌·원본 해상도 확인·PNG/JPEG/BMP 저장·클립보드 복사를 지원 |
| 검증 | `dotnet build` 경고 0 / 오류 0, `dotnet test` 436 passed / 0 failed |

자세한 내용은 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)의 `v0.7.3` 항목을 참고하세요.

---

## 라이선스

MIT License