lacvet/AX-Copilot-Codex
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
15b675d9c4ae0957f78e64ba57096df443319ee7
AX-Copilot-Codex/README.md
lacvet 15b675d9c4
Some checks failed
Release Gate / gate (push) Has been cancelled
Details
권한 표시 카탈로그를 분리해 UI 표면 기준을 단일화 
- PermissionModePresentationCatalog 신규 추가: 모드 라벨/설명/아이콘/색을 단일 소스로 관리

- ChatWindow 권한 팝업에서 하드코딩 튜플을 제거하고 카탈로그 기반 렌더링으로 전환

- 유지보수 관점에서 권한 표면 기준 변경 포인트를 1곳으로 축소

- README.md 업데이트 시각(2026-04-04 13:25 KST) 및 변경 이력 항목 갱신

- docs/DEVELOPMENT.md 연속 실행 27차 기록 추가

- 검증: dotnet build 경고 0/오류 0, slash+operation mode 필터 테스트 43건 통과
2026-04-04 13:26:34 +09:00

298 lines
18 KiB
Markdown
Raw Blame History

# 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 13:25 (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`로 추가해 시나리오 기반 검증 기준을 명문화 |
| 권한 모드 표면 통일 | 권한 표시 명칭을 `활용하지 않음/소극 활용/적극 활용/계획 중심/완전 자동/질문 없이 진행`으로 통일하고 팝업 선택 순서를 동일 체계로 재정렬 |
| 권한 기본 동작/순환 보강 | Chat 탭 기본 권한을 `활용하지 않음`으로 적용하고, `/sandbox-toggle` 및 AX Agent 설정 권한 순환을 같은 순서(`활용하지 않음→소극→적극→계획→완전 자동→질문 없이 진행`)로 맞춤 |
| 운영 모드 회귀 점검 강화 | `OperationModePolicyTests`, `OperationModeReadinessTests`, `LlmOperationModeTests` 필터 테스트(18건)를 통과해 internal/external 차단·허용 경로를 재검증 |
| 권한 팝업 밀도 재정돈 | 권한 섹션 헤더/카드/행의 패딩·폰트·줄간격을 조정해 과밀 영역을 완화하고 Codex/Claude형 스캔 속도에 맞춤 |
| 좌측/컴포저 라벨 정리 | 좌측 기본 카테고리 라벨을 `주제 선택/작업 선택`으로 통일하고, 입력 상단 바 패딩·간격을 미세 조정해 단일 라인 정돈 강화 |
| 체크리스트 실행 결과 기록 | `docs/UI_UX_CHECKLIST.md`에 2026-04-04 12:22 기준 점검 결과(운영모드 필터 18건 + 전체 436건 통과)를 기록 |
| 권한 상태 표시 간소화 | 권한 상태 텍스트(`/permissions`, `/allowed-tools`)를 운영 모드 포함 축약형으로 정리하고 권한 버튼 툴팁에 동일 정보를 반영 |
| 설정창 외부 진입 안정화 | AX Agent 설정창 오픈 시 리소스 병합 실패를 방어하고, 외부 진입 경로를 Dispatcher 기반으로 안정화 |
| 모델 라벨 반응형 보강 | 컴포저 상단 모델 라벨에 말줄임(`MaxWidth` + `CharacterEllipsis`)을 적용해 좁은 폭에서 레이아웃 깨짐을 방지 |
| 슬래시 탐색 순서 정합화 | `/` 팝업의 방향키/휠/Home/End 이동 기준을 렌더 순서(핀/최근 정렬 적용 순서)로 통일해 스크롤·선택 체감 불일치를 해소 |
| 권한 요청창 한국어/인코딩 복구 | `PermissionRequestWindow`의 깨진 문자열을 복구하고 권한 선택/위험도/미리보기 문구를 한국어 기준으로 정리 |
| slash 명령 카탈로그 분리 | `ChatWindow` 내부 대형 slash 사전을 `SlashCommandCatalog`로 분리해 입력 계층 결합도를 낮추고 유지보수 범위를 축소 |
| slash 조회 API 전환 | 내장 slash 매칭/조회 경로를 `SlashCommandCatalog.MatchBuiltinCommands`/`TryGetEntry`로 통일 |
| 권한 표시 카탈로그 분리 | 권한 모드 라벨/설명/아이콘/색을 `PermissionModePresentationCatalog`로 분리해 팝업 표면 기준을 단일화 |
| 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
Reference in New Issue View Git Blame Copy Permalink