240 lines
7.2 KiB
Markdown
240 lines
7.2 KiB
Markdown
# 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+,` → 테마 탭)에서 클릭 한 번으로 즉시 미리보기 적용.
|
|
|
|
---
|
|
|
|
## 변경 이력
|
|
|
|
### v1.6.1 — 전체 점검 수정
|
|
|
|
| 분류 | 내용 |
|
|
|------|------|
|
|
| 빌드 오류 수정 | `using System.IO` 누락, `Key.Enter`/`Key.Return` 중복 switch 케이스, `EnumDisplayMonitors` 람다 타입 혼합, `icon.ico` 다이아몬드 픽셀 보석 아이콘으로 교체, nullable 역참조 경고 |
|
|
| 런타임 버그 수정 | JSON 스킬 경로 파싱(`field[0` 형식 오류 방지), 클립보드 서비스 스레드 안전성, 디바운스 타이머 원자적 교체, 설정 백업 실패 로깅 |
|
|
| 보안 수정 | JSON 스킬 `ActionUrl` 실행 전 `http`/`https` 스킴 검증 추가 |
|
|
| 데드 코드 제거 | `SystemCommandHandler` no-op `timer`/`alarm` 항목 제거 |
|
|
|
|
자세한 내용은 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)의 "v1.6 3차 전체 점검 수정" 섹션을 참고하세요.
|
|
|
|
---
|
|
|
|
## 라이선스
|
|
|
|
MIT License
|
|
|