Home

스마트 터미널 명령 교정기

Story 1 — 사용자의 잘못된 명령어 자동 교정할 수 있다.

[Frontend Tasks]

Task ID	Task Description	Acceptance Criteria
S1-FE1	잘못된 명령 입력 시 AI API로 전달하는 실패 처리 로직 구현	- executeCommand 파싱 실패 시 자동으로 AI 교정 API 호출
S1-FE2	AI가 교정한 명령어를 터미널에 표시하는 UI 구현	- 터미널에 "[AI 수정]" 태그가 함께 출력
S1-FE3	교정된 명령을 executeCommand로 재실행하는 로직 구현	- AI 반환 명령어가 정상 실행되어 창/파일 등이 올바르게 동작해야 함
S1-FE4	교정 실패 시 fallback 오류 메시지 표시	- AI 결과가 없거나 명령어 유효성 검증 실패 시 기존 오류 메시지 표시

[Backend Tasks]

Task ID	Task Description	Acceptance Criteria
S1-BE1	잘못된 명령 교정용 AI 프롬프트 설계	- 오타, 잘못된 JSON, 누락된 key 등을 교정하는 규칙을 포함해야 함
S1-BE2	/api/ai/command-correct 엔드포인트 구현	- input 명령어를 받고 corrected 명령어를 JSON으로 반환
S1-BE3	교정된 명령어 유효성 검사 로직 구현	- 반환된 명령이 실제로 내부 명령어(spaced, structured) 규격을 반드시 충족
S1-BE4	AI 실패 시 에러 메시지 반환 처리	- 유효한 명령 생성 불가 시 “교정할 수 없음” 메시지 반환

Story 2 — 사용자의 자연어 명령을 OS 명령 변환으로 변환할 수 있다.

[Frontend Tasks]

Task ID	Task Description	Acceptance Criteria
S2-FE1	자연어 입력 감지 후 AI API 호출하는 로직 구현	- 명령어 형태가 아니면 자동으로 자연어로 판단해 AI API 호출
S2-FE2	자연어 입력을 표시하는 UI 스타일 추가	- 터미널 출력 앞에 "[자연어]" 태그 표시
S2-FE3	변환된 명령어를 executeCommand로 실행하는 기능 구현	- 자연어 → 명령 변환 후 창 열기/이동이 정상 동작해야 함
S2-FE4	자연어 변환 실패 시 사용자 안내 메시지 출력	- “이 요청을 이해하지 못했습니다” 같은 사용자 친화적 메시지 표시

[Backend Tasks]

Task ID	Task Description	Acceptance Criteria
S2-BE1	자연어 → OS 명령 변환 프롬프트 템플릿 설계	- “메모장 열어줘”, “창 크게 해줘” 같은 요청을 단일 구조화 명령으로 변환 가능
S2-BE2	/api/ai/command-correct 엔드포인트 자연어 모드 확장	- input이 자연어일 경우 structured command를 생성해 response로 반환
S2-BE3	변환된 명령어 유효성 검사	- fileType, windowId 등 key가 유효한 값인지 검증
S2-BE4	자연어 변환 실패 시 친절한 fallback 메시지 반환	- 변환 불가능 시 설명 포함한 오류 메시지 반환

API

POST /api/ai/command

Body

{
  "mode": "correct" | "natural",
  "input": "사용자가 입력한 문자열"
}

Response

{
  "type": "corrected",
  "correctedCommand": "win:open { ... }",
  "raw": "AI의 원문 출력"
}

---

구현 가이드

현재 프로젝트 구조 분석

명령어 처리 흐름

1. 프론트엔드: frontend/src/components/terminal/Terminal.tsx

   • 사용자 입력 → handleEnter() → parseCommand() → executeCommand()

2. 명령 파싱: frontend/src/components/terminal/commandHandler.ts

   • parseCommand(input): 명령어와 stdin 데이터 분리
   • executeCommand(parsedInput, windowId): 명령 실행
   • COMMAND_HANDLER_MAP: 내장 명령어 (clear, date, echo, help, status, uname, win:*)
   • 내장 명령어가 아니면 → callSyscall() → 백엔드 /api/syscall 호출

3. 백엔드: backend/src/syscall/syscall.controller.ts

   • /api/syscall POST 엔드포인트
   • exec, ls, pwd, cd, cat, mkdir, rm, write 등 처리

구현 필요 사항

1. 백엔드 AI 모듈 생성

제안 디렉토리 구조

backend/src/ai/
├── ai.module.ts              # AI 모듈 정의
├── ai.controller.ts           # /api/ai/command 엔드포인트
├── ai.service.ts              # AI API 호출 및 명령 교정/변환 로직
├── dto/
│   ├── ai-command.dto.ts      # 요청/응답 DTO
│   └── ai-command.type.ts     # 타입 정의
└── util/
    └── command-validator.util.ts  # 교정된 명령어 유효성 검사

수정할 파일:

• backend/src/app.module.ts: AiModule import 추가

구현 포인트:

• AI 서비스 (OpenAI, Claude 등) API 호출
• 프롬프트 템플릿 설계 (명령 교정용, 자연어 변환용)
• 교정된 명령어가 실제 명령어 형식에 맞는지 검증
• 에러 처리 및 fallback 메시지

2. 프론트엔드 AI 통합

수정할 파일

• frontend/src/components/terminal/commandHandler.ts
  • executeCommand() 함수 수정: 에러 발생 시 AI 교정 시도
  • 자연어 감지 로직 추가

새로 생성할 파일

• frontend/src/api/ai/aiApi.ts: AI API 호출 함수
• frontend/src/api/ai/aiDto.ts: 타입 정의 및 가드 함수

구현 포인트

• 명령 파싱 실패 시 자동으로 AI 교정 API 호출
• 자연어 입력 감지 (명령어 형식이 아닌 경우)
• AI 응답을 파싱하여 executeCommand() 재실행
• UI에 "[AI 수정]" 또는 "[자연어]" 태그 표시

파일별 수정 제안

백엔드

파일	작업	내용
backend/src/ai/ai.module.ts	생성	AI 모듈 정의, AiService, AiController 등록
backend/src/ai/ai.controller.ts	생성	POST /api/ai/command 엔드포인트 구현
backend/src/ai/ai.service.ts	생성	AI API 호출, 프롬프트 생성, 응답 파싱
backend/src/ai/dto/ai-command.dto.ts	생성	요청/응답 DTO 정의
backend/src/ai/util/command-validator.util.ts	생성	교정된 명령어 유효성 검사
backend/src/app.module.ts	수정	AiModule import 추가

프론트엔드

파일	작업	내용
frontend/src/api/ai/aiApi.ts	생성	callAiCommand() 함수 구현
frontend/src/api/ai/aiDto.ts	생성	타입 정의 및 가드 함수
frontend/src/components/terminal/commandHandler.ts	수정	AI 교정/변환 로직 통합
frontend/src/components/terminal/Terminal.tsx	수정	UI 태그 표시 로직 추가