Skip to content

Home

Jump to bottom
MinJeong Hong edited this page Nov 25, 2025 · 13 revisions

스마트 터미널 명령 교정기

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 태그 표시 로직 추가

타입 제안

1) AI API Request 타입

export interface AiCommandRequest {
  mode: 'correct' | 'natural';
  input: string;
}

2) AI API Response 타입

export interface AiCommandResponse {
  type: 'corrected' | 'natural';
  correctedCommand: string; // 실제 실행 명령어 → FE 응답에서 꼭 필수니까 키 이름 바꾸지말아야함 (바꿀거면 공지 필수)📌
  raw: string;              // AI 원문 출력 (디버깅용)
}

3) BE 내부에서 사용할 ParsedCommand

export interface ParsedCommand {
  command: string;                // "win:open"
  payload: Record<string, any>;   // { x: 100, y: 200 }
}

4) 에러 Response 타입

export interface AiErrorResponse {
  error: string;           // "InvalidCommand" | "JsonParseError" | ...
  message: string;         // 사람에게 보여줄 설명
}

5) 서버 기준 명령어 목록

BE 검증 목적

export type CommandType = 'win:open' | 'win:move' | 'win:list' | 'win:close'; // 예시본이므로 직접 확인 후 가공 필수

Clone this wiki locally