Shrimp Task Manager

# 🦐 Shrimp Task Manager Viewer [Shrimp Task Manager](https://github.com/cjo4m06/mcp-shrimp-task-manager)로 생성된 작업을 보고 관리하기 위한 현대적이고 React 기반의 웹 인터페이스입니다. 이 시각적 인터페이스를 통해 자세한 작업 정보를 확인하고, 여러 프로젝트에서 진행 상황을 추적하며, AI 에이전트 상호작용을 위해 작업 UUID를 쉽게 복사할 수 있습니다. ## Shrimp Task Viewer를 사용하는 이유는? Claude와 같은 AI 에이전트와 함께 MCP 서버로 Shrimp Task Manager를 사용할 때, 이 뷰어는 작업 생태계에 대한 필수적인 가시성을 제공합니다: - **시각적 작업 개요**: 모든 작업, 상태, 종속성 및 진행 상황을 깔끔한 탭 인터페이스에서 확인 - **UUID 관리**: 작업 배지를 클릭하여 `"Use task manager to complete this shrimp task: [UUID]"`와 같은 명령에 UUID를 즉시 복사 - **병렬 실행**: 여러 터미널을 열고 AI 작업 열(🤖)을 사용하여 병렬 AI 에이전트 실행을 위한 작업 지침 복사 - **실시간 업데이트**: 직접 파일 경로 읽기로 항상 현재 작업 상태 확인 - **다중 프로젝트 지원**: 드래그 가능한 프로필 탭으로 다양한 프로젝트의 작업 관리 MCP 서버로 Shrimp Task Manager를 설정하는 정보는 [메인 저장소](https://github.com/cjo4m06/mcp-shrimp-task-manager)를 참조하세요. ## 📖 자세한 페이지 문서 ### 📋 작업 페이지 메인 작업 페이지는 작업 관리의 컨트롤 센터입니다. 조직 및 실행을 위한 강력한 기능과 함께 선택된 프로필의 모든 작업에 대한 포괄적인 보기를 제공합니다.  **주요 기능:** - **작업 테이블**: 작업 #, 상태, 에이전트, 생성 날짜, 이름, 종속성 및 작업을 포함한 정렬 가능한 열로 모든 작업 표시 - **상태 배지**: 색상 코딩된 배지 (🟡 대기 중, 🔵 진행 중, 🟢 완료됨, 🔴 차단됨) - **에이전트 할당**: 특정 AI 에이전트를 작업에 할당하는 드롭다운 선택기 - **에이전트 뷰어 팝업**: 눈 아이콘(👁️)을 클릭하여 에이전트를 탐색하고 선택할 수 있는 팝업 열기 - **종속성 열**: 클릭하여 탐색할 수 있는 기능이 있는 연결된 작업 ID 표시 - **작업 열**: AI 작업 실행을 위한 강력한 로봇 이모티콘(🤖) 포함 - **작업 세부 정보 탐색**: 작업 세부 정보를 볼 때 ← 이전 및 다음 → 버튼을 사용하여 작업 간 빠른 탐색 #### 🤖 로봇 이모티콘 - AI 작업 실행 작업 열의 로봇 이모티콘은 AI 지원 작업 실행을 위한 강력한 기능입니다:  **작동 방식:** 1. **🤖 이모티콘을 클릭**하여 작업 실행 지침을 클립보드로 복사 2. **에이전트가 있는 작업**: `use the built in subagent located in ./claude/agents/[agent-name] to complete this shrimp task: [task-id] please when u start working mark the shrimp task as in progress` 복사 3. **에이전트가 없는 작업**: `Use task manager to complete this shrimp task: [task-id] please when u start working mark the shrimp task as in progress` 복사 4. **시각적 피드백**: 복사 작업을 확인하기 위해 이모티콘이 잠시 ✓로 변경 **사용 사례:** - **병렬 실행**: 다양한 AI 에이전트와 함께 여러 터미널 창을 열고 동시 작업 처리를 위한 지침 붙여넣기 - **에이전트 전문화**: 적절한 작업에 전문 에이전트(예: `react-components.md`, `database-specialist.md`) 할당 - **빠른 핸드오프**: 복잡한 명령을 입력하지 않고 AI 에이전트에게 작업을 빠르게 위임 #### 🤖 AI 기반 일괄 에이전트 할당 작업 페이지에는 이제 OpenAI의 GPT-4를 사용하는 AI 기반 일괄 에이전트 할당이 포함됩니다: **사용 방법:** 1. **작업 선택**: 체크박스를 사용하여 에이전트 할당이 필요한 여러 작업 선택 2. **일괄 작업 표시줄**: 선택된 작업 수를 표시하는 파란색 표시줄 "🤖 AI 에이전트 할당 (X개 작업 선택됨)" 나타남 3. **원클릭 할당**: 버튼을 클릭하여 GPT-4가 작업을 분석하고 적절한 에이전트 할당 4. **자동 매칭**: AI가 작업 설명, 종속성 및 에이전트 기능을 고려 **설정 요구사항:** 1. **API 키 구성**: 설정 → 전역 설정으로 이동 2. **OpenAI 키 입력**: 필드에 OpenAI API 키 붙여넣기 (설정 시 ✓ 구성됨으로 표시) 3. **대체 방법**: `OPENAI_API_KEY` 또는 `OPEN_AI_KEY_SHRIMP_TASK_VIEWER` 환경 변수 설정 4. **API 키 받기**: [OpenAI 플랫폼](https://platform.openai.com/api-keys)을 방문하여 키 생성  *전역 설정 페이지는 OpenAI API 키를 구성하기 위한 보안 필드를 제공합니다* #### 📝 작업 세부 정보 보기 작업 행을 클릭하여 포괄적인 정보가 포함된 자세한 작업 보기를 엽니다: **기능:** - **전체 작업 정보**: 완전한 설명, 메모, 구현 가이드 및 확인 기준 보기 - **작업 탐색**: 목록으로 돌아가지 않고 작업 간 이동하기 위한 ← 이전 및 다음 → 버튼 - **관련 파일**: 줄 번호가 포함된 작업과 관련된 모든 파일 확인 - **종속성 그래프**: 작업 종속성의 시각적 표현 - **편집 모드**: 편집을 클릭하여 작업 세부 정보 수정 (완료되지 않은 작업) - **빠른 작업**: 작업 ID 복사, 원시 JSON 보기 또는 작업 삭제 **탐색의 이점:** - **효율적인 검토**: 여러 작업을 순서대로 빠르게 검토 - **컨텍스트 보존**: 작업 간 이동하면서 세부 보기 유지 - **키보드 지원**: 더 빠른 탐색을 위한 화살표 키 사용 ### 📜 프로젝트 이력 페이지 프로젝트 이력 페이지는 Shrimp Task Manager가 저장한 완료된 작업의 스냅샷을 표시하여 프로젝트 진화에 대한 귀중한 통찰을 제공합니다.  **기능:** - **타임라인 보기**: 프로젝트의 작업 상태에 대한 이력 스냅샷 탐색 - **메모리 파일**: 새 세션을 시작할 때 Shrimp Task Manager가 자동으로 저장 - **작업 진화**: 작업이 생성부터 완료까지 어떻게 진행되었는지 추적 - **메모 시스템**: 이력 항목에 개인 주석 추가  **탐색:** - 이력 항목을 클릭하여 해당 시점의 자세한 작업 상태 보기 - 탐색 버튼을 사용하여 다양한 스냅샷 간 이동 - 메인 작업 보기와 마찬가지로 이력 작업 검색 및 필터링 ### 🤖 하위 에이전트 페이지 하위 에이전트 페이지를 통해 최적의 실행을 위해 작업에 할당할 수 있는 전문 AI 에이전트를 관리할 수 있습니다.  **기능:** - **에이전트 라이브러리**: `.claude/agents` 폴더의 모든 사용 가능한 에이전트 보기 - **AI 지시 열**: 로봇 이모티콘(🤖)을 클릭하여 에이전트 사용 지침을 즉시 복사 - 예시: `use subagent debugger.md located in ./claude/agents to perform:` - 에이전트 경로를 수동으로 입력하거나 구문을 기억할 필요 없음 - 시각적 피드백으로 클립보드로의 성공적인 복사 확인 - **에이전트 편집기**: 에이전트 생성 및 수정을 위한 내장 마크다운 편집기 - **색상 코딩**: 시각적 조직을 위한 에이전트에 색상 할당 - **에이전트 할당**: 작업 테이블의 드롭다운을 통해 작업에 에이전트를 쉽게 할당 - **에이전트 뷰어 팝업**: 눈 아이콘(👁️)을 클릭하여 에이전트 탐색 및 선택  **에이전트 할당 워크플로:**  1. 작업 테이블의 드롭다운에서 **에이전트 선택** 2. **또는 눈 아이콘(👁️)을 클릭**하여 에이전트 뷰어 팝업 열기 3. 팝업에서 **에이전트 탐색**하여 작업에 적합한 에이전트 찾기 4. **자동 저장**으로 작업의 메타데이터 업데이트 5. **로봇 이모티콘 사용**하여 에이전트별 실행 지침 복사  *에이전트 뷰어 팝업을 통해 모든 사용 가능한 에이전트를 탐색하고 각 작업에 가장 적합한 에이전트를 선택할 수 있습니다* ### 🎨 템플릿 페이지 Shrimp Task Manager가 다양한 유형의 작업을 분석하고 실행하는 방법을 안내하는 AI 지침 템플릿을 관리합니다.  **기능:** - **템플릿 편집기**: 구문 강조 기능이 있는 전체 마크다운 편집기 - **템플릿 유형**: 기본, 사용자 정의 및 사용자 정의+추가 상태 - **실시간 미리보기**: 활성화하기 전에 템플릿 효과 확인 - **내보내기/가져오기**: 팀 구성원과 템플릿 공유 ### ⚙️ 전역 설정 시스템 전체 에이전트에 액세스하기 위한 Claude 폴더 경로를 포함하여 시스템 전체 설정을 구성합니다. **설정 포함:** - **Claude 폴더 경로**: 전역 `.claude` 폴더 경로 설정 - **API 키 구성**: AI 서비스를 위한 환경 변수 관리 - **언어 기본 설정**: 지원되는 언어 간 전환 ## 🌟 기능 ### 🏷️ 현대적인 탭 인터페이스 - **드래그 가능한 탭**: 탭을 드래그하여 프로필 재정렬 - **전문적인 디자인**: 콘텐츠와 완벽하게 연결되는 브라우저 스타일 탭 - **시각적 피드백**: 명확한 활성 탭 표시 및 호버 효과 - **새 프로필 추가**: 인터페이스 디자인과 일치하는 통합 "+ 탭 추가" 버튼 ### 🔍 고급 검색 및 필터링 - **실시간 검색**: 이름, 설명, 상태 또는 ID로 즉시 작업 필터링 - **정렬 가능한 열**: 열 헤더를 클릭하여 모든 필드로 정렬 - **TanStack 테이블**: 페이지네이션 및 필터링이 가능한 강력한 테이블 컴포넌트 - **반응형 디자인**: 데스크톱, 태블릿 및 모바일에서 완벽하게 작동 ### 🔄 지능적인 자동 새로고침 - **구성 가능한 간격**: 5초, 10초, 15초, 30초, 1분, 2분 또는 5분 중 선택 - **스마트 컨트롤**: 간격 선택이 가능한 자동 새로고침 토글 - **시각적 표시기**: 로딩 상태 및 새로고침 상태 - **수동 새로고침**: 온디맨드 업데이트를 위한 전용 새로고침 버튼 ### 📊 포괄적인 작업 관리 - **작업 통계**: 총계, 완료됨, 진행 중 및 대기 중 작업에 대한 실시간 카운트 - **프로필 관리**: 직관적인 인터페이스를 통한 프로필 추가/제거/재정렬 - **지속적인 설정**: 세션 간 프로필 구성 저장 - **핫 리로드**: 즉시 업데이트되는 개발 모드 ### 🤖 AI 지원 기능 - **일괄 에이전트 할당**: 여러 작업을 선택하고 GPT-4를 사용하여 가장 적절한 에이전트를 자동으로 할당 - **OpenAI 통합**: 전역 설정 또는 환경 변수를 통해 API 키 구성 - **지능적인 매칭**: AI가 최적의 할당을 위해 작업 설명과 에이전트 기능을 분석 - **오류 안내**: API 키가 구성되지 않은 경우 명확한 지침 ### 📚 버전 관리 및 이력 - **Git 통합**: 타임스탬프 메시지와 함께 tasks.json에 대한 모든 변경 사항을 자동 Git 커밋으로 추적 - **완전한 감사 추적**: 표준 Git 도구를 사용하여 작업 수정의 전체 이력 검토 - **논블로킹 작업**: Git 실패가 작업 관리를 중단하지 않음 - **격리된 저장소**: 작업 이력이 프로젝트 저장소와 별도로 추적됨 ### 🎨 전문적인 UI/UX - **다크 테마**: 개발 환경에 최적화 - **반응형 레이아웃**: 모든 화면 크기에 적응 - **접근성**: 완전한 키보드 탐색 및 스크린 리더 지원 - **인터랙티브 요소**: 전체적인 호버 툴팁 및 시각적 피드백 ## 🚀 빠른 시작 ### 설치 및 설정 1. **작업 뷰어 디렉토리로 복제 및 이동** ```bash cd path/to/mcp-shrimp-task-manager/tools/task-viewer ``` 2. **의존성 설치** ```bash npm install ``` 3. **React 애플리케이션 빌드** ```bash npm run build ``` 4. **서버 시작** ```bash npm start ``` 뷰어는 `http://localhost:9998`에서 사용할 수 있습니다 ### 개발 모드 핫 리로드를 사용한 개발: ```bash # API 서버와 개발 서버를 모두 시작 npm run start:all # 또는 별도로 실행: npm start # 포트 9998의 API 서버 npm run dev # 포트 3000의 Vite 개발 서버 ``` 앱은 파일 변경 시 자동 재빌드와 함께 `http://localhost:3000`에서 사용할 수 있습니다. ### 운영 배포 #### 표준 배포 ```bash # 운영용 빌드 npm run build # 운영 서버 시작 npm start ``` #### Systemd 서비스 (리눅스) 자동 시작 및 프로세스 관리를 위해: 1. **서비스로 설치** ```bash sudo ./install-service.sh ``` 2. **서비스 관리** ```bash # 상태 확인 systemctl status shrimp-task-viewer # 시작/정지/재시작 sudo systemctl start shrimp-task-viewer sudo systemctl stop shrimp-task-viewer sudo systemctl restart shrimp-task-viewer # 로그 보기 journalctl -u shrimp-task-viewer -f # 자동 시작 비활성화/활성화 sudo systemctl disable shrimp-task-viewer sudo systemctl enable shrimp-task-viewer ``` 3. **서비스 제거** ```bash sudo ./uninstall-service.sh ``` ## 🖥️ 사용법 ### 시작하기 1. **서버 시작**: ```bash npm start ``` **참고**: 아직 앱을 빌드하지 않았거나 핫 리로드를 사용한 개발 모드를 원하는 경우 `npm run start:all`을 대신 사용하세요. 2. **브라우저 열기**: `http://127.0.0.1:9998` (운영) 또는 `http://localhost:3000` (개발)로 이동 3. **첫 번째 프로필 추가**: - "**+ 탭 추가**" 버튼 클릭 - 설명적인 프로필 이름 입력 (예: "팀 알파 작업") - tasks.json이 포함된 shrimp 데이터 폴더 경로 입력 - **팁:** 터미널에서 폴더로 이동하고 `pwd`를 입력하여 전체 경로 확인 - "**프로필 추가**" 클릭 4. **작업 관리**: - 탭을 사용하여 프로필 간 전환 - 검색 상자를 사용하여 작업 검색 - 헤더를 클릭하여 열 정렬 - 필요에 따라 자동 새로고침 구성 ### 탭 관리 - **프로필 전환**: 탭을 클릭하여 해당 프로필로 전환 - **탭 재정렬**: 탭을 드래그하여 선호하는 순서로 재배열 - **새 프로필 추가**: "**+ 탭 추가**" 버튼 클릭 - **프로필 제거**: 탭의 ×를 클릭 (확인과 함께) ### 검색 및 필터링 - **전역 검색**: 검색 상자에 입력하여 모든 작업 필드에서 필터링 - **열 정렬**: 열 헤더를 클릭하여 정렬 (다시 클릭하여 역순) - **페이지네이션**: 내장 페이지네이션 컨트롤로 대규모 작업 목록 탐색 - **실시간 업데이트**: 입력하는 대로 즉시 검색 및 정렬 업데이트 ### 자동 새로고침 구성 1. **자동 새로고침 활성화**: "자동 새로고침" 체크박스 선택 2. **간격 설정**: 드롭다운에서 선택 (5초~5분) 3. **수동 새로고침**: 언제든지 즉시 새로고침을 위해 🔄 버튼 클릭 4. **시각적 피드백**: 새로고침 작업 중 스피너 표시 ## 🔧 구성 ### 환경 변수 터미널 세션 간 환경 변수를 지속적으로 만들려면 셸 구성 파일에 추가하세요: **Zsh를 사용하는 macOS/Linux** (최신 macOS 기본값): ```bash # ~/.zshrc에 추가 echo 'export SHRIMP_VIEWER_PORT=9998' >> ~/.zshrc echo 'export SHRIMP_VIEWER_HOST=127.0.0.1' >> ~/.zshrc # 구성 다시 로드 source ~/.zshrc ``` **Bash를 사용하는 Linux/Unix**: ```bash # ~/.bashrc에 추가 echo 'export SHRIMP_VIEWER_PORT=9998' >> ~/.bashrc echo 'export SHRIMP_VIEWER_HOST=127.0.0.1' >> ~/.bashrc # 구성 다시 로드 source ~/.bashrc ``` **셸 구성에 추가하는 이유?** - **지속성**: 터미널에서 `export`로 설정된 변수는 해당 세션에서만 지속됨 - **일관성**: 모든 새 터미널 창에서 이러한 설정 사용 - **편리성**: 서버를 시작할 때마다 변수를 설정할 필요 없음 **사용 가능한 변수**: ```bash SHRIMP_VIEWER_PORT=9998 # 서버 포트 (기본값: 9998) SHRIMP_VIEWER_HOST=127.0.0.1 # 서버 호스트 (로컬호스트만) OPENAI_API_KEY=sk-... # AI 에이전트 할당을 위한 OpenAI API 키 OPEN_AI_KEY_SHRIMP_TASK_VIEWER=sk-... # OpenAI 키를 위한 대체 env var ``` ### 개발 구성 - **핫 리로드를 사용한 개발 (개발 권장)**: ```bash npm run start:all # API 서버 (9998) + Vite 개발 서버 (3000) 실행 ``` **start:all을 사용하는 이유?** 이 명령은 API 서버와 Vite 개발 서버를 동시에 실행합니다. 전체 API 기능을 유지하면서 UI 변경에 대한 즉시 핫 모듈 교체(HMR)를 받을 수 있습니다. 수동 새로고침 없이 `http://localhost:3000`에서 브라우저에 변경 사항이 즉시 나타납니다. - **API 서버만 (운영 또는 API 테스트용)**: ```bash npm start # 포트 9998에서 실행 ``` **API 서버만 사용하는 이유?** 운영 파일을 빌드하고 운영에서와 같이 완전한 앱을 테스트하려거나 API 엔드포인트만 필요할 때 사용합니다. - **운영용 빌드 및 서빙**: ```bash npm run build && npm start # 빌드 후 포트 9998에서 서빙 ``` **운영용 빌드를 하는 이유?** 운영 빌드는 JavaScript 축소, 데드 코드 제거, 자산 번들링을 효율적으로 수행하여 코드를 최적화합니다. 이로 인해 로드 시간이 빨라지고 최종 사용자의 성능이 향상됩니다. 배포할 때는 항상 운영 빌드를 사용하세요. ### 프로필 데이터 저장 **프로필 데이터 관리 이해**: Task Viewer는 지속성과 실시간 정확성을 모두 우선시하는 하이브리드 데이터 저장 방식을 사용합니다. 프로필 구성(탭 이름, 폴더 경로, 탭 순서 등)은 홈 디렉토리의 JSON 설정 파일에 로컬로 저장되며, 작업 데이터는 실시간으로 프로젝트 폴더에서 직접 읽습니다. - **설정 파일**: `~/.shrimp-task-viewer-settings.json` 홈 디렉토리의 이 숨겨진 파일은 탭 이름, 폴더 경로, 탭 순서 및 기타 기본 설정을 포함한 모든 프로필 구성을 저장합니다. 첫 번째 프로필을 추가할 때 자동으로 생성되고 변경할 때마다 업데이트됩니다. 필요한 경우 이 파일을 수동으로 편집할 수 있지만 유효한 JSON 형식을 유지하도록 주의하세요. - **작업 파일**: 지정된 폴더 경로에서 직접 읽기 (업로드 없음) 파일 사본을 업로드하고 저장하는 기존 웹 애플리케이션과 달리 Task Viewer는 지정된 폴더 경로에서 직접 `tasks.json` 파일을 읽습니다. 이를 통해 다시 업로드하거나 동기화할 필요 없이 항상 작업의 현재 상태를 볼 수 있습니다. 프로필을 추가할 때 뷰어에게 tasks.json 파일을 찾을 위치를 간단히 알려주는 것입니다. - **핫 리로드**: 개발 변경 사항이 자동으로 재빌드됨 개발 모드(`npm run dev`)에서 실행할 때 소스 코드에 대한 모든 변경 사항이 자동 재빌드와 브라우저 새로고침을 트리거합니다. 이는 React 컴포넌트, 스타일 및 서버 코드에 적용되어 개발을 더 빠르고 효율적으로 만듭니다. ### Git 작업 이력 **자동 버전 관리**: v3.0부터 Shrimp Task Manager는 Git을 사용하여 모든 작업 변경 사항을 자동으로 추적합니다. 이는 수동 구성 없이 완전한 감사 추적을 제공합니다. - **저장소 위치**: `<shrimp-data-directory>/.git` 각 프로젝트는 `.mcp.json` 파일에 구성된 데이터 디렉토리에 자체 Git 저장소를 갖습니다. 이는 충돌이나 간섭을 방지하기 위해 프로젝트의 메인 Git 저장소와 완전히 분리되어 있습니다. - **이력 보기**: 표준 Git 명령을 사용하여 작업 이력 탐색 ```bash cd <shrimp-data-directory> git log --oneline # 커밋 이력 보기 git show <commit-hash> # 특정 변경 사항 확인 git diff HEAD~5 # 5개 커밋 전과 비교 ``` - **커밋 형식**: 모든 커밋에 타임스탬프와 설명적 메시지 포함 ``` [2025-08-07T13:45:23-07:00] 새 작업 추가: 사용자 인증 구현 [2025-08-07T14:12:10-07:00] 작업 업데이트: 로그인 검증 수정 [2025-08-07T14:45:55-07:00] 일괄 작업 작업: append 모드, 6개 작업 ``` - **복구**: 필요한 경우 이전 작업 상태 복원 ```bash cd <shrimp-data-directory> git checkout <commit-hash> -- tasks.json # 특정 버전 복원 git reset --hard <commit-hash> # 이전 상태로 전체 재설정 ``` ## 🏗️ 기술 아키텍처 ### 기술 스택 - **프론트엔드**: React 19 + 핫 리로드 개발을 위한 Vite - **테이블 컴포넌트**: 고급 테이블 기능을 위한 TanStack React Table - **스타일링**: 다크 테마와 반응형 디자인이 포함된 사용자 정의 CSS - **백엔드**: RESTful API를 가진 Node.js HTTP 서버 - **빌드 시스템**: 빠른 개발과 최적화된 운영 빌드를 위한 Vite ### 파일 구조 **프로젝트 조직**: Task Viewer는 관심사를 분리하고 코드베이스를 탐색하고 확장하기 쉽게 만드는 깔끔한 모듈식 구조를 따릅니다. 각 디렉토리와 파일은 애플리케이션 아키텍처에서 특정 목적을 가집니다. ``` task-viewer/ ├── src/ # React 애플리케이션 소스 코드 │ ├── App.jsx # 메인 React 컴포넌트 - 상태, 프로필, 탭 관리 │ ├── components/ # 재사용 가능한 React 컴포넌트 │ │ ├── TaskTable.jsx # 작업 표시 및 정렬을 위한 TanStack 테이블 │ │ ├── Help.jsx # 마크다운 렌더링이 포함된 README 뷰어 │ │ └── ReleaseNotes.jsx # 구문 강조가 포함된 버전 이력 │ ├── data/ # 정적 데이터 및 구성 │ │ └── releases.js # 릴리스 메타데이터 및 버전 정보 │ └── index.css # 다크 테마가 포함된 완전한 스타일링 시스템 ├── releases/ # 릴리스 노트 마크다운 파일 및 이미지 │ ├── v*.md # 개별 릴리스 노트 파일 │ └── *.png # 릴리스용 스크린샷 및 이미지 ├── dist/ # 운영 빌드 출력 (자동 생성) │ ├── index.html # 최적화된 HTML 진입점 │ └── assets/ # 번들된 JS, CSS 및 기타 자산 ├── server.js # Express와 유사한 Node.js API 서버 ├── cli.js # 서비스 관리를 위한 명령줄 인터페이스 ├── vite.config.js # 개발/운영을 위한 빌드 도구 구성 ├── package.json # 프로젝트 메타데이터, 의존성 및 npm 스크립트 ├── install-service.sh # 리눅스 systemd 서비스 설치 프로그램 └── README.md # 포괄적인 문서 (이 파일) ``` **주요 디렉토리 설명**: - **`src/`**: 모든 React 소스 코드를 포함합니다. 대부분의 UI 변경을 여기서 수행합니다. - **`dist/`**: 자동 생성되는 운영 빌드입니다. 이 파일들을 직접 편집하지 마세요. - **`releases/`**: 관련 이미지와 함께 마크다운 형식의 릴리스 노트를 저장합니다. - **루트 파일**: 빌드, 서빙 및 배포를 처리하는 구성 및 서버 파일들입니다. ### API 엔드포인트 - `GET /` - React 애플리케이션 제공 - `GET /api/agents` - 모든 구성된 프로필 목록 - `GET /api/tasks/{profileId}` - 특정 프로필의 작업 반환 - `POST /api/add-profile` - 폴더 경로와 함께 새 프로필 추가 - `DELETE /api/remove-profile/{profileId}` - 프로필 제거 - `PUT /api/rename-profile/{profileId}` - 프로필 이름 변경 - `PUT /api/update-profile/{profileId}` - 프로필 설정 업데이트 - `GET /api/readme` - 도움말 탭용 README 콘텐츠 반환 - `GET /releases/*.md` - 릴리스 노트 마크다운 파일 제공 - `GET /releases/*.png` - 릴리스 노트 이미지 제공 ## 🛠️ 개발 ### 개발 환경 설정 ```bash # 의존성 설치 npm install # 핫 리로드를 사용한 개발 서버 시작 npm run dev # 개발 서버는 http://localhost:3000에서 실행 # 백엔드 API 서버는 http://localhost:9998에서 실행 ``` ### 운영용 빌드 ```bash # 최적화된 운영 번들 빌드 npm run build # 파일들이 dist/ 디렉토리에 생성됨 # 운영 서버 시작 npm start ``` ### 인터페이스 확장 모듈식 React 아키텍처로 쉽게 확장할 수 있습니다: 1. **새 컴포넌트 추가**: `src/components/`에 생성 2. **스타일링 수정**: CSS 사용자 정의 속성으로 `src/index.css` 편집 3. **기능 추가**: 새 상태와 기능으로 `App.jsx` 확장 4. **API 통합**: `server.js`에 엔드포인트 추가 ## 🔒 보안 및 성능 ### 보안 기능 - **로컬호스트 바인딩**: 서버가 로컬 머신에서만 접근 가능 - **직접 파일 액세스**: 파일시스템 경로에서 직접 작업 파일 읽기 - **외부 의존성 없음**: 최소한의 공격 표면을 가진 자체 포함 - **CORS 보호**: CORS 헤더로 보호되는 API 엔드포인트 ### 성능 최적화 - **핫 모듈 교체**: 즉시 개발 업데이트 - **코드 분할**: 최적화된 번들 로딩 - **효율적인 재렌더링**: React 최적화 패턴 - **캐싱**: 빠른 로드를 위한 정적 자산 캐싱 - **반응형 이미지**: 모든 기기 크기에 최적화 ## 🐛 문제 해결 ### 일반적인 문제 **서버가 시작되지 않음** ```bash # 포트가 사용 중인지 확인 lsof -i :9998 # 기존 프로세스 종료 pkill -f "node.*server.js" # 다른 포트 시도 SHRIMP_VIEWER_PORT=8080 node server.js ``` **도움말/Readme 탭에 HTML 표시** 도움말 탭에 README 내용 대신 HTML이 표시되는 경우, 새 API 엔드포인트를 로드하기 위해 서버를 다시 시작해야 합니다: ```bash # 서버 중지 (Ctrl+C) 후 재시작 npm start ``` **핫 리로드가 작동하지 않음** ```bash # 개발 의존성이 설치되었는지 확인 npm install # 개발 서버 재시작 npm run dev ``` **작업이 로드되지 않음** 1. `tasks.json` 파일에 유효한 JSON이 포함되어 있는지 확인 2. 파일 권한이 읽기 가능한지 확인 3. 오류 메시지는 브라우저 콘솔에서 확인 4. 수동 새로고침 버튼을 사용하여 데이터 다시 로드 **빌드 오류** ```bash # node_modules를 지우고 재설치 rm -rf node_modules package-lock.json npm install # Vite 캐시 지우기 rm -rf dist/ npm run build ``` ## 📋 변경 로그 ### 버전 3.0.0 (최신) - 2025-08-07 #### 🚀 주요 기능 - **에이전트 관리 시스템**: 전문 AI 에이전트의 포괄적인 관리 - **AI 기반 일괄 에이전트 할당**: OpenAI GPT-4를 사용한 지능적인 에이전트 할당 - **Git 버전 관리**: 모든 작업 변경 사항의 자동 추적 - **프로젝트 이력 보기**: 과거 작업 상태에 대한 완전한 가시성 - **템플릿 관리**: AI 지침을 위한 강력한 템플릿 사용자 정의 - **국제화 지원**: 영어, 중국어, 스페인어, 한국어 지원 - **향상된 UI**: 현대적인 인터페이스와 탐색 개선 ### 버전 2.1.0 - 2025-07-29 #### 🚀 주요 기능 - **직접 파일 경로 지원**: 라이브 업데이트를 위한 파일 업로드를 직접 폴더 경로 입력으로 교체 - **도움말/Readme 탭**: 마크다운 렌더링이 포함된 문서 탭 추가 - **릴리스 노트 탭**: 이미지 지원이 포함된 인앱 릴리스 노트 뷰어 - **클릭 가능한 종속성**: 종속 작업 간 쉬운 탐색 - **AI 작업 열**: 작업 완료를 위한 AI 지침 복사 - **향상된 UUID 관리**: 작업 배지를 클릭하여 UUID 복사 - **프로필 편집**: 프로필 이름 변경 및 프로젝트 루트 구성 - **ES 모듈 지원**: 더 나은 호환성을 위해 ES 모듈로 변환 #### 🐛 중요한 수정 - **정적 파일 복사 문제 수정**: 파일이 이제 `/tmp/`에 정적 복사본을 생성하는 대신 지정된 경로에서 직접 읽힘 ### 버전 1.0.3 - 2025-07-26 #### 🧪 테스트 및 안정성 - **포괄적인 테스트 스위트**: Vitest를 사용한 전체 테스트 커버리지 추가 - **컴포넌트 테스트**: 모든 컴포넌트를 위한 React Testing Library 테스트 - **통합 테스트**: 서버 및 API 엔드포인트의 종단 간 테스트 - **버그 수정**: 프로필 관리에서 멀티파트 폼 데이터 처리 해결 ### 버전 1.0.2 - 2025-07-26 #### 🎨 작업 세부 정보 보기 - **탭 내 탐색**: 모달을 원활한 탭 내 작업 세부 정보로 교체 - **뒤로 가기 버튼**: 작업 목록으로 쉬운 탐색 - **향상된 UX**: 팝업 방해 없는 더 나은 워크플로 ### 버전 1.0.1 - 2025-07-13 #### 🎨 주요 UI 개편 - **현대적인 탭 인터페이스**: 드래그 앤 드롭 재정렬이 가능한 전문적인 브라우저 스타일 탭 - **연결된 디자인**: 탭과 콘텐츠 간 원활한 시각적 연결 - **향상된 레이아웃**: 더 나은 워크플로를 위해 검색 및 컨트롤 위치 재배치 #### ⚡ 향상된 기능 - **구성 가능한 자동 새로고침**: 5초에서 5분까지 간격 선택 - **고급 검색**: 모든 작업 필드에서 실시간 필터링 - **정렬 가능한 열**: 헤더를 클릭하여 모든 열로 정렬 - **핫 리로드 개발**: 개발 중 즉시 업데이트 #### 🔧 기술적 개선 - **React 아키텍처**: React 19 + Vite를 사용한 완전한 재작성 - **TanStack 테이블**: 페이지네이션이 포함된 전문적인 테이블 컴포넌트 - **반응형 디자인**: 중단점 최적화를 통한 모바일 우선 접근법 - **성능**: 최적화된 렌더링 및 효율적인 상태 관리 ### 버전 1.0.0 - 2025-07-01 #### 🚀 초기 릴리스 - **기본 뷰어**: 기본 웹 인터페이스가 포함된 초기 구현 - **프로필 관리**: 작업 프로필 추가 및 제거 - **서버 API**: 작업 데이터를 위한 RESTful 엔드포인트 - **작업 표시**: 여러 프로젝트의 작업 보기 ## 📄 라이선스 MIT 라이선스 - 자세한 내용은 메인 프로젝트 라이선스를 참조하세요. ## 🤝 기여 이 도구는 MCP Shrimp Task Manager 프로젝트의 일부입니다. 기여를 환영합니다! 1. 저장소를 포크하세요 2. 기능 브랜치를 생성하세요 (`git checkout -b feature/amazing-feature`) 3. 적절한 테스트와 함께 변경하세요 4. 변경사항을 커밋하세요 (`git commit -m 'Add amazing feature'`) 5. 브랜치에 푸시하세요 (`git push origin feature/amazing-feature`) 6. 풀 리퀘스트를 제출하세요 ### 개발 가이드라인 - React 모범 사례와 훅 패턴을 따르세요 - 반응형 디자인 원칙을 유지하세요 - 해당하는 경우 적절한 TypeScript 타입을 추가하세요 - 다양한 브라우저와 기기에서 테스트하세요 - 새 기능에 대한 문서를 업데이트하세요 --- **행복한 작업 관리를! 🦐✨** React, Vite 및 현대 웹 기술로 ❤️를 담아 제작되었습니다.