chore(release): bump framework and 8 skills to v4.1.0 (MINOR — OpenCode AI agent integration)

2026-08-29 23:20:53 +09:00
parent de2c0e6824
commit 6de15350c0
19 changed files with 680 additions and 93 deletions
@@ -0,0 +1,130 @@
+# 🦙 OpenCode (`anomalyco/opencode`) — Ollama 연동 및 기본 모델 설정 가이드
+
+본 문서는 **OpenCode** CLI/TUI 환경에서 로컬 **Ollama** 프로바이더와 모델을 기본값(Default)으로 연결하고 최적화하여 사용하는 방법을 정리한 가이드입니다.
+
+---
+
+## 1. 설정 파일 위치 (`opencode.jsonc` vs `opencode.json`)
+
+OpenCode는 **JSONC (JSON with Comments)** 형식을 공식 지원하므로 주석(`//`, `/* */`) 작성이 가능한 `opencode.jsonc`를 기본 설정 파일로 사용합니다. (`.json`과 `.jsonc` 둘 다 동일하게 인식됩니다.)
+
+* **전역 설정 경로 (추천)**:
+  * `~/.config/opencode/opencode.jsonc` (또는 `~/.config/opencode/opencode.json`)
+* **프로젝트별 로컬 설정 경로**:
+  * `<project-root>/opencode.json` (특정 프로젝트 루트 디렉터리에 위치)
+
+---
+
+## 2. 권장 설정 내용 (`opencode.jsonc`)
+
+`~/.config/opencode/opencode.jsonc` 파일에 아래와 같이 구성합니다:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+
+  // 1. 기본 실행 모델 (형식: "provider_id/model_id")
+  "model": "ollama/qwen2.5-coder:32b",
+
+  // 2. Ollama 프로바이더 상세 엔드포인트 및 모델 정의
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama",
+      "options": {
+        "baseURL": "http://127.0.0.1:11434/v1"
+      },
+      "models": {
+        "qwen2.5-coder:32b": {
+          "name": "Qwen 2.5 Coder 32B"
+        },
+        "glm-5.3:cloud": {
+          "name": "GLM 5.3 Cloud"
+        }
+      }
+    }
+  }
+}
+```
+
+> [!TIP]
+> `qwen2.5-coder:32b` 대신 본인의 머신에 설치된 Ollama 모델 태그명(예: `qwen2.5-coder:14b`, `llama3.1:8b`, `deepseek-r1:14b` 등)을 기재하시면 됩니다.
+
+---
+
+## 3. Ollama 사용 시 필수 사전 준비 (Critical)
+
+### 3.1 Ollama 서비스 구동 및 API 확인
+```bash
+# Ollama 모델 목록 확인
+ollama list
+
+# OpenAI 호환 v1 엔드포인트 응답 확인
+curl http://127.0.0.1:11434/v1/models
+```
+
+### 3.2 컨텍스트 윈도우(`num_ctx`) 확장
+Ollama의 기본 컨텍스트 크기는 **4,096 토큰**으로 매우 작아서, 에이전트가 파일 트리나 긴 소스 코드를 읽을 때 컨텍스트 오버플로우가 발생할 수 있습니다. `Modelfile`을 작성하여 32K(32,768) 이상으로 확장하는 것을 강력히 권장합니다.
+
+```bash
+# 1) Modelfile 생성
+cat << 'EOF' > Modelfile
+FROM qwen2.5-coder:32b
+PARAMETER num_ctx 32768
+EOF
+
+# 2) 확장된 커스텀 모델 빌드
+ollama create qwen2.5-coder-32k -f Modelfile
+```
+* 빌드 후 `opencode.jsonc`의 `"model"`을 `"ollama/qwen2.5-coder-32k"`로 지정합니다.
+
+### 3.3 Tool Calling(함수 호출) 지원 모델 선택
+OpenCode는 파일 읽기/수정, 셸 실행 등을 모델의 **Tool Calling** 기능으로 처리합니다.
+* **추천 모델**: `qwen2.5-coder` (7b/14b/32b), `llama3.1` (8b/70b), `mistral-nemo`
+
+---
+
+## 4. 실행 및 런타임 제어
+
+### 4.1 기본 실행 (설정 파일 적용)
+```bash
+# 기본 설정된 Ollama 모델로 TUI 실행
+opencode
+```
+
+### 4.2 CLI 플래그로 특정 모델 즉시 실행 (`-m`)
+```bash
+# 대화형 TUI 실행
+opencode -m "ollama/qwen2.5-coder:32b"
+
+# 비대화형(Headless) 무인 단발 태스크 실행
+opencode run -m "ollama/qwen2.5-coder:32b" "tests/ 단위 테스트를 실행하고 실패하는 테스트를 고쳐줘"
+```
+
+### 4.3 TUI 실행 중 대화식 모델 전환
+* OpenCode 대화창에서 `Tab` 키를 누르거나 프롬프트에 `/models`를 입력하여 등록된 모델 목록 중 원하는 모델을 즉시 선택할 수 있습니다.
+
+---
+
+## 5. Multi-Agent Mux (MAM) 연동 예시
+
+MAM 환경에서 OpenCode를 reviewer/creator 에이전트로 띄울 때의 표준 명령어:
+
+```bash
+# 1. 세션 생성 및 온보딩
+bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
+  --workspace "$(pwd)" \
+  --agent "opencode" \
+  --role "reviewer" \
+  --session "reviewer-opencode-01" \
+  --herdr-session "multi-agent-mux" \
+  --herdr-workspace "mam-agent" \
+  --onboard
+
+# 2. 세션 대화 복원 (Resume)
+bash .agents/skills/multi-agent-mux-resume/scripts/resume_session.sh \
+  --workspace "$(pwd)" \
+  --agent "opencode" \
+  --session "reviewer-opencode-01" \
+  --herdr-session "multi-agent-mux"
+```