synapse-sdk 1.0.0b13__py3-none-any.whl → 1.0.0b15__py3-none-any.whl

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/cli-usage.md

@@ -0,0 +1,280 @@
+---
+id: cli-usage
+title: CLI 사용 가이드
+sidebar_position: 4
+---
+
+# CLI 사용 가이드
+
+Synapse SDK는 설정부터 플러그인 개발 및 코드 편집까지 개발 워크플로우를 관리하기 위한 강력한 대화형 CLI를 제공합니다.
+
+## 시작하기
+
+대화형 CLI 실행:
+
+```bash
+synapse
+```
+
+또는 특정 명령을 직접 실행:
+
+```bash
+# 개발 도구 즉시 시작
+synapse --dev-tools
+
+# 도움말 표시
+synapse --help
+```
+
+## 메인 메뉴 옵션
+
+`synapse`를 실행하면 메인 메뉴가 표시됩니다:
+
+```
+🚀 Synapse SDK
+Select an option:
+  🌐 Run Dev Tools
+  💻 Open Code-Server IDE
+  ⚙️  Configuration
+  🔌 Plugin Management
+  🚪 Exit
+```
+
+## 🌐 Run Dev Tools
+
+다음 기능을 포함한 Synapse 개발 도구 대시보드를 실행합니다:
+
+- **대화형 UI**: Agent와 작업 관리를 위한 웹 기반 대시보드
+- **실시간 모니터링**: Agent 상태 및 작업 실행의 실시간 보기
+- **플러그인 관리**: UI를 통한 플러그인 업로드, 테스트, 관리
+
+### 사용법
+```bash
+# CLI 메뉴에서 개발 도구 실행
+synapse
+
+# 또는 직접 시작
+synapse --dev-tools
+```
+
+## 💻 Open Code-Server IDE
+
+플러그인 개발을 위한 웹 기반 VS Code 환경을 엽니다. Agent 기반 및 로컬 code-server 인스턴스를 모두 지원합니다.
+
+### Agent Code-Server
+
+Agent에서 실행되는 원격 code-server에 연결:
+
+- **자동 설정**: Synapse가 작업공간을 설정하고 의존성을 설치
+- **플러그인 암호화**: 로컬 플러그인 코드가 암호화되어 안전하게 전송
+- **작업공간 동기화**: 로컬 프로젝트가 Agent 환경에서 사용 가능
+
+### 로컬 Code-Server
+
+로컬 code-server 인스턴스 실행:
+
+- **포트 감지**: `~/.config/code-server/config.yaml`에서 포트를 자동으로 읽음
+- **폴더 매개변수**: 올바른 작업공간 디렉토리로 열림
+- **브라우저 통합**: 적절한 URL로 자동으로 브라우저를 열음
+
+### 사용 예제
+
+```bash
+# 대화형 메뉴 (권장)
+synapse
+# "💻 Open Code-Server IDE" 선택
+
+# 직접 명령
+synapse code-server
+
+# 특정 옵션과 함께
+synapse code-server --agent my-agent --workspace /path/to/project
+
+# 브라우저를 자동으로 열지 않음
+synapse code-server --no-open-browser
+```
+
+### Code-Server 옵션
+
+| 옵션 | 설명 | 기본값 |
+|--------|-------------|---------|
+| `--agent` | 사용할 특정 Agent ID | 현재 Agent 또는 프롬프트 |
+| `--workspace` | 프로젝트 디렉토리 경로 | 현재 디렉토리 |
+| `--open-browser/--no-open-browser` | 브라우저 자동 열기 | `--open-browser` |
+
+### 로컬 Code-Server 설치
+
+code-server가 로컬에 설치되지 않은 경우 CLI가 설치 지침을 제공합니다:
+
+```bash
+# 권장: 설치 스크립트
+curl -fsSL https://code-server.dev/install.sh | sh
+
+# npm 사용
+npm install -g code-server
+
+# yarn 사용
+yarn global add code-server
+```
+
+더 많은 옵션은 다음을 참조하세요: https://coder.com/docs/code-server/latest/install
+
+## ⚙️ Configuration
+
+다음을 설정하기 위한 대화형 설정 마법사:
+
+- **백엔드 연결**: API 엔드포인트 및 인증 설정
+- **Agent 선택**: 개발 Agent 선택 및 설정
+- **토큰 관리**: 액세스 토큰 및 인증 관리
+
+### 설정 파일
+
+Synapse는 다음 위치에 설정을 저장합니다:
+- **백엔드 설정**: `~/.synapse/devtools.yaml`
+- **Agent 설정**: `~/.synapse/devtools.yaml` (Agent 섹션)
+- **Code-Server 설정**: `~/.config/code-server/config.yaml`
+
+## 🔌 Plugin Management
+
+포괄적인 플러그인 개발 및 관리 도구:
+
+### 새 플러그인 생성
+
+```bash
+synapse
+# "🔌 Plugin Management" → "Create new plugin" 선택
+```
+
+대화형 마법사가 다음을 생성합니다:
+- 플러그인 디렉토리 구조
+- 설정 파일 (`config.yaml`)
+- 예제 플러그인 코드
+- 요구사항 및 의존성
+
+### 플러그인 로컬 실행
+
+다른 환경에서 플러그인 테스트:
+
+```bash
+# 스크립트 실행 (로컬)
+synapse plugin run my_action '{"param": "value"}' --run-by script
+
+# Agent 실행 (원격)
+synapse plugin run my_action '{"param": "value"}' --run-by agent
+
+# 백엔드 실행 (클라우드)
+synapse plugin run my_action '{"param": "value"}' --run-by backend
+```
+
+### 플러그인 게시
+
+Synapse 백엔드에 플러그인 배포:
+
+```bash
+synapse
+# "🔌 Plugin Management" → "Publish plugin" 선택
+```
+
+옵션:
+- **디버그 모드**: 자세한 로깅으로 배포 테스트
+- **프로덕션 모드**: 실제 사용을 위한 배포
+
+## 명령 참조
+
+### 주요 명령어
+
+```bash
+# 대화형 CLI (메인 메뉴)
+synapse
+
+# 개발 도구
+synapse --dev-tools
+
+# 직접 명령
+synapse config         # 설정 마법사
+synapse devtools       # 개발 대시보드
+synapse code-server    # 코드 편집 환경
+synapse plugin         # 플러그인 관리
+```
+
+### Code-Server 명령
+
+```bash
+synapse code-server [OPTIONS]
+
+Options:
+  --agent TEXT                    Agent 이름 또는 ID
+  --open-browser / --no-open-browser
+                                  브라우저에서 열기 [기본값: open-browser]
+  --workspace TEXT                작업공간 디렉토리 경로 (기본값: 현재 디렉토리)
+  --help                          이 메시지를 표시하고 종료.
+```
+
+### 플러그인 명령어
+
+```bash
+# 플러그인 생성
+synapse plugin create
+
+# 플러그인 실행
+synapse plugin run ACTION PARAMS [OPTIONS]
+
+# 플러그인 게시
+synapse plugin publish [OPTIONS]
+```
+
+## 팁 및 모범 사례
+
+### Code-Server 개발
+
+1. **플러그인 감지**: code-server를 열 때 Synapse는 작업공간에 플러그인이 포함되어 있는지 자동으로 감지하고 Agent로의 안전한 전송을 위해 암호화합니다.
+
+2. **작업공간 경로**: Agent 작업공간은 일반적으로 `/home/coder/workspace`를 사용합니다 - 이는 컨테이너화된 환경에서 정상입니다.
+
+3. **포트 설정**: 로컬 code-server 포트는 설정 파일에서 읽어오며, 설정이 없으면 8070을 기본값으로 사용합니다.
+
+### 설정 관리
+
+1. **토큰 보안**: API 토큰을 안전하게 저장하고 정기적으로 순환
+2. **Agent 선택**: Agent의 목적을 식별하기 위해 설명적인 Agent 이름 사용
+3. **백엔드 URL**: 백엔드 URL이 개발 환경에서 접근 가능한지 확인
+
+### 플러그인 개발
+
+1. **로컬 테스트**: 배포 전에 항상 `--run-by script`로 플러그인을 로컬에서 테스트
+2. **디버그 모드**: 초기 배포 시 디버그 모드를 사용하여 문제를 조기에 발견
+3. **버전 제어**: git을 사용하여 플러그인 변경사항을 추적하고 버전 관리
+
+## 문제 해결
+
+### Code-Server 문제
+
+**문제**: "Code-server is not available" 오류
+- **해결방법**: Agent에 code-server 지원이 활성화되어 있는지 확인
+
+**문제**: 브라우저가 자동으로 열리지 않음
+- **해결방법**: 제공된 URL을 브라우저에 수동으로 복사
+
+**문제**: 잘못된 포트가 표시됨
+- **해결방법**: 올바른 포트 설정을 위해 `~/.config/code-server/config.yaml` 확인
+
+### 설정 문제
+
+**문제**: "No backend configured"
+- **해결방법**: `synapse config`를 실행하여 백엔드 연결 설정
+
+**문제**: "Invalid token (401)"
+- **해결방법**: 새 API 토큰을 생성하고 설정 업데이트
+
+**문제**: "Connection timeout"
+- **해결방법**: 네트워크 연결 및 백엔드 URL 접근성 확인
+
+### 플러그인 문제
+
+**문제**: 작업공간에서 플러그인이 감지되지 않음
+- **해결방법**: 디렉토리에 유효한 `config.yaml` 파일이 있는지 확인
+
+**문제**: 플러그인 실행 실패
+- **해결방법**: 플러그인 의존성 및 구문 확인, 먼저 로컬에서 테스트
+
+더 많은 문제 해결 도움은 [문제 해결 가이드](./troubleshooting.md)를 참조하세요.

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/concepts/index.md

@@ -0,0 +1,38 @@
+---
+id: index
+title: Core Concepts
+sidebar_position: 1
+---
+
+# Core Concepts
+
+Synapse SDK의 기본 개념을 이해합니다.
+
+## 아키텍처
+
+전체 시스템 아키텍처 및 설계 원칙에 대해 알아보세요.
+
+## 플러그인 시스템
+
+플러그인의 작동 방식, 카테고리 및 실행 방법을 이해합니다.
+
+## 클라이언트
+
+다양한 클라이언트 유형과 사용 사례:
+- BackendClient: API 작업용
+- AgentClient: 분산 실행용
+
+## 실행 방법
+
+플러그인을 실행하는 다양한 방법:
+- **JOB**: 모니터링이 포함된 장기 실행 작업
+- **TASK**: 빠르고 간단한 작업
+- **RESTAPI**: 모델 및 API 서빙
+
+## 데이터 플로우
+
+시스템을 통해 입력에서 출력까지 데이터가 흐르는 방식입니다.
+
+## 보안
+
+인증, 권한 부여 및 보안 모범 사례입니다.

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/configuration.md

@@ -0,0 +1,83 @@
+---
+id: configuration
+title: 구성
+sidebar_position: 8
+---
+
+# 구성
+
+환경과 사용 사례에 맞게 Synapse SDK를 구성하세요.
+
+## 구성 방법
+
+Synapse SDK를 구성하는 세 가지 방법이 있습니다:
+
+1. **Synapse CLI**
+2. **환경 변수**
+3. **구성 파일**
+
+## CLI
+
+대화형 구성 메뉴는 Synapse SDK를 구성하는 쉬운 방법을 제공합니다:
+
+```bash
+$ synapse config
+```
+
+다음을 수행할 수 있는 대화형 메뉴가 열립니다:
+- 백엔드 호스트 및 API 토큰 구성
+- 에이전트 선택 또는 수동 구성
+- 현재 구성 보기
+
+### 주요 기능:
+- **일반 텍스트 토큰 표시**: 쉬운 검증을 위해 토큰이 일반 텍스트로 표시됩니다
+- **연결 테스트**: 백엔드 또는 에이전트 구성 후 연결이 자동으로 테스트됩니다
+- **시작 지연 없음**: 연결 확인은 설정 구성 시에만 발생하며, CLI 시작 시에는 발생하지 않습니다
+
+## 구성 파일
+
+`~/.synapse/config.json`에 구성 파일을 생성하세요:
+
+```json
+{
+  "backend": {
+    "host": "https://api.synapse.sh",
+    "token": "your-api-token"
+  },
+  "agent": {
+    "id": "agent-uuid-123",
+    "name": "My Development Agent",
+    "token": "your-agent-token"
+  }
+}
+```
+
+## 플러그인 관리
+
+CLI는 대화형 플러그인 관리 인터페이스를 제공합니다:
+
+```bash
+$ synapse
+# "플러그인 관리" 선택
+```
+
+### 사용 가능한 옵션:
+
+1. **새 플러그인 생성**: cookiecutter를 사용하여 템플릿에서 새 플러그인을 생성합니다
+2. **플러그인 로컬 실행**: 구성 가능한 매개변수로 플러그인을 실행하는 대화형 인터페이스
+3. **플러그인 게시**: 디버그 모드 옵션과 함께 구성된 백엔드에 플러그인을 게시합니다
+
+### 플러그인 게시
+
+플러그인을 게시할 때:
+- **디버그 모드**: 개발용으로 기본적으로 활성화됩니다
+- **백엔드 통합**: 구성된 백엔드 설정을 사용합니다
+- **연결 테스트**: 게시 전에 백엔드 연결을 확인합니다
+- **오류 처리**: 오류 발생 시 중단하고 사용자 확인을 기다립니다
+
+### 플러그인 개발 워크플로
+
+1. **생성**: CLI를 사용하여 새 플러그인 템플릿 생성
+2. **개발**: 생성된 구조를 따라 플러그인 코드 작성
+3. **테스트**: 대화형 인터페이스를 통해 플러그인을 로컬에서 실행
+4. **게시**: 디버그 옵션과 함께 구성된 백엔드에 배포

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/contributing.md

@@ -0,0 +1,306 @@
+---
+id: contributing
+title: 기여하기
+sidebar_position: 12
+---
+
+# Synapse SDK에 기여하기
+
+Synapse SDK에 기여해 주셔서 감사합니다! 이 가이드는 프로젝트 기여를 시작하는 데 도움이 됩니다.
+
+## 개발 환경 설정
+
+### 사전 요구사항
+
+- Python 3.8 이상
+- Git
+- 가상 환경 도구 (venv, conda 등)
+
+### 시작하기
+
+1. **저장소 포크 및 복제**
+   ```bash
+   git clone https://github.com/yourusername/synapse-sdk.git
+   cd synapse-sdk
+   ```
+
+2. **가상 환경 생성**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # Windows: .venv\Scripts\activate
+   ```
+
+3. **의존성 설치**
+   ```bash
+   pip install -r requirements.txt
+   pip install -r requirements.test.txt
+   ```
+
+## 코드 포맷팅 및 품질
+
+### Ruff 포맷팅
+
+코드 포맷팅 및 린팅에 **Ruff**를 사용합니다. 모든 기여는 우리의 포맷팅 표준을 따라야 합니다.
+
+#### 필수 명령어
+
+코드 변경 사항을 제출하기 전에 다음 명령어를 실행하세요:
+
+```bash
+# 모든 Python 코드 포맷팅
+ruff format .
+
+# 린팅 문제 수정
+ruff check --fix .
+
+# 남은 문제 확인
+ruff check .
+```
+
+#### 포맷팅 워크플로우
+
+1. **변경사항 작성** - Python 코드를 작성하거나 수정
+2. **Ruff로 포맷팅** - `ruff format .`을 실행하여 일관된 포맷팅 적용
+3. **린팅 문제 수정** - `ruff check --fix .`를 실행하여 코드 품질 문제 해결
+4. **변경사항 확인** - 포맷팅된 코드를 검토하여 정확성 보장
+5. **변경사항 커밋** - 적절히 포맷팅된 코드로 커밋 생성
+
+#### IDE 통합
+
+IDE가 Ruff를 자동으로 실행하도록 설정하세요:
+
+- **VS Code**: Ruff 확장 프로그램 설치
+- **PyCharm**: Ruff를 외부 도구로 설정
+- **Vim/Neovim**: ruff-lsp 또는 유사한 플러그인 사용
+
+### 코드 스타일 가이드라인
+
+- **줄 길이**: `pyproject.toml`의 프로젝트별 설정 따르기
+- **Import 정렬**: Ruff가 import 정리를 처리하도록 함
+- **타입 힌트**: 적절한 곳에 타입 어노테이션 사용
+- **독스트링**: Google 스타일 독스트링 형식 따르기
+- **주석**: 복잡한 로직에 대해 명확하고 간결한 주석 작성
+
+## 테스팅
+
+### 테스트 실행
+
+```bash
+# 모든 테스트 실행
+pytest
+
+# 특정 테스트 파일 실행
+pytest tests/plugins/utils/test_config.py
+
+# 커버리지와 함께 실행
+pytest --cov=synapse_sdk
+```
+
+### 테스트 작성
+
+- 모든 새로운 기능에 대해 테스트 작성
+- 시나리오를 설명하는 서술적 테스트 이름 사용
+- 긍정적 및 부정적 테스트 케이스 모두 포함
+- 외부 의존성을 적절히 모킹
+- 높은 테스트 커버리지 유지
+
+#### 테스트 구조
+
+```python
+class TestMyFeature:
+    """MyFeature 기능 테스트."""
+    
+    def test_feature_success_case(self):
+        """성공적인 기능 작동 테스트."""
+        # Arrange
+        input_data = {"key": "value"}
+        
+        # Act
+        result = my_feature(input_data)
+        
+        # Assert
+        assert result == expected_output
+    
+    def test_feature_error_case(self):
+        """기능 오류 처리 테스트."""
+        with pytest.raises(ValueError, match="Expected error message"):
+            my_feature(invalid_input)
+```
+
+## 플러그인 개발
+
+### 새로운 플러그인 유틸리티 생성
+
+새로운 플러그인 유틸리티를 추가할 때:
+
+1. **적절한 모듈에 추가**:
+   - 설정 유틸리티 → `synapse_sdk/plugins/utils/config.py`
+   - 액션 유틸리티 → `synapse_sdk/plugins/utils/actions.py`
+   - 레지스트리 유틸리티 → `synapse_sdk/plugins/utils/registry.py`
+
+2. **포괄적인 독스트링 포함**:
+   ```python
+   def my_utility_function(param: str) -> Dict[str, Any]:
+       """함수에 대한 간단한 설명.
+       
+       Args:
+           param: 매개변수 설명.
+           
+       Returns:
+           반환값 설명.
+           
+       Raises:
+           ValueError: 입력이 유효하지 않을 때.
+           
+       Examples:
+           >>> my_utility_function("example")
+           {'result': 'processed'}
+       """
+   ```
+
+3. **`__all__` 내보내기에 추가**
+4. **포괄적인 테스트 작성**
+5. **문서 업데이트**
+
+### 플러그인 카테고리
+
+플러그인 카테고리 작업 시:
+
+- 가능하면 기존 카테고리 사용
+- 명명 규칙 따르기: `snake_case`
+- 적절한 검증 및 오류 처리 추가
+- 새 카테고리 추가 시 카테고리 enum 업데이트
+
+## 문서화
+
+### API 문서화
+
+- 모든 공개 함수에 대한 독스트링 업데이트
+- 독스트링에 사용 예제 포함
+- 더 나은 IDE 지원을 위한 타입 힌트 추가
+- 오류 조건 및 예외 문서화
+
+### 사용자 문서화
+
+관련 문서 파일 업데이트:
+
+- **API 참조**: `docs/api/plugins/utils.md`
+- **기능 가이드**: `docs/features/plugins/index.md`
+- **변경 로그**: `docs/changelog.md`
+- **예제**: 실용적인 사용 예제 추가
+
+### 문서화 형식
+
+다음을 포함한 명확하고 간결한 언어 사용:
+
+- 모든 함수에 대한 코드 예제
+- 매개변수 및 반환값 설명
+- 오류 처리 예제
+- 호환성을 깨뜨리는 변경에 대한 마이그레이션 가이드
+
+## Pull Request 프로세스
+
+### 제출 전
+
+1. **포맷팅 및 린팅 실행**:
+   ```bash
+   ruff format .
+   ruff check --fix .
+   ```
+
+2. **모든 테스트 실행**:
+   ```bash
+   pytest
+   ```
+
+3. **필요에 따라 문서 업데이트**
+
+4. **중요한 변경사항에 대한 변경 로그 항목 추가**
+
+### Pull Request 가이드라인
+
+- **명확한 제목**: PR이 달성하는 것 설명
+- **자세한 설명**: 변경사항과 동기 설명
+- **이슈 참조**: 관련 GitHub 이슈에 링크
+- **테스트 커버리지**: 새 코드가 테스트되었는지 확인
+- **문서화**: 사용자 대상 변경사항에 대한 문서 업데이트
+
+### PR 템플릿
+
+```markdown
+## 설명
+변경사항에 대한 간단한 설명
+
+## 변경 유형
+- [ ] 버그 수정
+- [ ] 새로운 기능
+- [ ] 호환성을 깨뜨리는 변경
+- [ ] 문서 업데이트
+
+## 테스트
+- [ ] 로컬에서 테스트 통과
+- [ ] 새 기능에 대한 새 테스트 추가
+- [ ] Ruff로 코드 포맷팅됨
+
+## 문서화
+- [ ] API 문서 업데이트됨
+- [ ] 필요시 사용자 가이드 업데이트됨
+- [ ] 변경 로그 항목 추가됨
+```
+
+## 코드 리뷰
+
+### 리뷰 기준
+
+- **기능성**: 코드가 의도된 대로 작동
+- **품질**: 코딩 표준 및 모범 사례 준수
+- **테스팅**: 적절한 테스트 커버리지
+- **문서화**: 공개 API에 대한 명확한 문서
+- **성능**: 명백한 성능 문제 없음
+- **보안**: 보안 취약점 없음
+
+### 피드백 대응
+
+- 모든 리뷰어 의견 처리
+- 피드백이 불명확하면 설명 요청
+- 요청된 변경사항을 신속히 수행
+- 변경 후 포맷팅 및 테스트 재실행
+
+## 프로젝트 구조
+
+프로젝트 조직 이해:
+
+```
+synapse_sdk/
+├── plugins/
+│   ├── utils/              # 플러그인 유틸리티 (모듈식)
+│   │   ├── config.py       # 설정 유틸리티
+│   │   ├── actions.py      # 액션 관리
+│   │   └── registry.py     # 레지스트리 유틸리티
+│   ├── categories/         # 플러그인 카테고리 구현
+│   └── models.py          # 핵심 플러그인 모델
+├── clients/               # API 클라이언트
+├── utils/                 # 일반 유틸리티
+└── devtools/             # 개발 도구
+
+tests/
+├── plugins/
+│   └── utils/            # 플러그인 유틸리티 테스트
+└── ...                   # 기타 테스트 모듈
+
+docs/                     # 문서
+├── api/                  # API 참조
+├── features/             # 기능 가이드
+└── changelog.md          # 변경 로그
+```
+
+## 도움 받기
+
+- **GitHub Issues**: 버그 신고 또는 기능 요청
+- **Discussions**: 질문하거나 아이디어 논의
+- **문서화**: 먼저 기존 문서 확인
+- **코드 리뷰**: 리뷰 중 설명 요청
+
+## 라이센스
+
+Synapse SDK에 기여함으로써 귀하의 기여가 프로젝트와 동일한 라이센스(MIT 라이센스) 하에 라이센스될 것에 동의합니다.