opencode-plusplus

# OpenCode++ OpenCode++는 공식 OpenCode Desktop 애플리케이션을 위한 Windows 우선 Harness 플러그인으로, AI가 코드를 생성하는 전체 과정을 가시적이고 검토 가능하게 만드는 것을 목표로 합니다. 모델이 무엇을 보았는지, 무엇을 차단했는지, 무엇을 실행하도록 요구했는지, 그리고 현재 증거가 실제로 무엇을 검증했는지를 보여줍니다. ## 해결하는 문제 AI 코딩 세션은 그럴듯해 보이는 diff를 생성할 수 있지만, 실제로는 잘못된 파일을 읽거나, 예상 범위를 벗어나 편집하거나, 관련 없는 명령을 실행하거나, 신선한 테스트 증거 없이 성공을 선언할 수 있습니다. OpenCode++는 OpenCode Desktop 주위에 검증 제어 평면을 추가하여 모델이 저장소 컨텍스트, 명확한 편집 경계, 추적 가능한 증거 및 최종 결정에 기반해 작업하도록 합니다. OpenCode++는 또 다른 채팅 앱이 아니며 모델을 대체하지도 않습니다. 이는 사용자 수준 데스크톱 플러그인으로, OpenCode가 이미 노출한 도구를 관찰하고 다음을 위한 Harness 도구를 제공합니다: - 무작정 검색하기 전에 관련 파일과 심볼을 선택; - 작업 경계와 필요한 검사를 준비; - 명령과 보호 경로를 가드; - 현재 작업 트리에 대해 정리된 실행 증거를 기록; - 정책, 신선도, 회귀, 환각 및 수렴 게이트를 평가; - 다음 단계가 수정, 재패키징, 인간 검토 또는 최종화인지 설명. ## 시스템 아키텍처 핵심 경계는 단순합니다: OpenCode는 여전히 파일을 읽고, 코드를 편집하고, 명령을 실행합니다. OpenCode++는 이러한 작업 주위에 결정론적 컨텍스트, 경계, 증거 검사 및 결정을 제공합니다. | 계층 | OpenCode++가 하는 일 | 주장하지 않는 것 | | --- | --- | --- | | 컨텍스트 등록 및 검색 | 관련 패키지, 파일, 심볼, 버전 및 의존성을 찾고 선택 및 거부된 파일을 설명. | 컨텍스트는 지침이지 허가나 증명이 아님. | | 가드 및 정책 | 명령, 보호 경로, 계약, 신선도, 회귀 및 필요한 작업을 검사. | 운영체제 샌드박스가 아님. | | 증거 | 명령 또는 CI 결과를 현재 작업 트리 해시 및 활성 증거 정책과 매칭. | 명령 통과만으로 비즈니스 정확성을 증명하지 못함. | | 개입 원장 | 관찰, 차단, 요청, 수정, 검증, 미해결 및 인간 검토 상태를 기록. | 예방이나 제안은 검증된 수정이 아님. | | 결정 및 대시보드 | 다음 허용 작업을 반환하고 데스크톱 결과 및 로컬 아티팩트에 기록된 사실을 표시. | 숨겨진 모델 사고 연쇄를 노출하거나 다른 모델을 호출하지 않음. | 정상 데스크톱 경로는 하나의 현재 OpenCode 모델과 하나의 프로세스 내 플러그인을 사용합니다. CLI와 MCP는 여전히 개발/호환성 표면이며, 설치나 일상 사용에는 필요하지 않습니다. ## 현재 기능 Windows 설치 프로그램은 **OpenCode++**라는 선택적 OpenCode 기본 모드를 추가합니다. 프롬프트 상자 하단의 모드 선택기에서 선택한 후 평소처럼 코딩 작업을 설명하면 됩니다. OpenCode++ 슬래시 명령을 기억할 필요가 없습니다. 해당 모드를 선택하면 그 프롬프트가 현재 OpenCode 모델에 프로세스 내 플러그인 도구를 사용하도록 지시합니다. 플러그인은 두 번째 모델이나 CLI 프로세스를 시작하지 않습니다. OpenCode Desktop 내에서 실행되며 감사 가능한 런타임 아티팩트를 저장소의 `.agent-context/` 디렉터리에 기록합니다. EXE 설치 프로그램은 사용자별 설치로 Windows x64에 적용되며 관리자 권한이 필요하지 않습니다. 기본적으로 플러그인은 오프라인으로 작동합니다: 원격 컨텍스트 소스를 가져오지 않고 두 번째 모델을 호출하지도 않습니다. 구성된 원격 소스나 피드백 전송은 명시적으로 활성화해야 합니다. 활성 OpenCode 모델이 여전히 읽기, 편집 및 명령 실행을 담당하며, OpenCode++는 이러한 작업 주위에 결정론적 도구와 게이트를 제공합니다. ## 설치 및 사용 1. GitHub Releases에서 `opencode-plusplus-setup-win-x64.exe`를 다운로드합니다. 2. OpenCode Desktop을 완전히 종료합니다. 3. EXE를 더블 클릭하고 설치 메시지를 수락합니다. 4. OpenCode Desktop을 재시작하고 저장소를 엽니다. 5. 모드 선택기에서 **OpenCode++**를 선택합니다. 6. 예를 들어 "로그인 타임아웃을 수정하고 회귀 테스트를 추가"와 같은 일반 요청을 입력합니다. 7. 선택한 모드가 작업 중 `prepare`, `retrieve`, `evaluate` 및 `next`를 호출하도록 합니다. Harness 게이트가 필요한 작업에서는 Build로 다시 전환하지 마십시오. 8. `evaluate` 또는 `next` 후 간결한 상태를 읽습니다. 단계 진행, 선택 및 거부된 파일, 결정 근거, 증거 신선도, 개입 및 최종 요약이 필요하면 `opencode_plusplus_dashboard`를 호출합니다. 9. 추적, 발견, 필요한 명령 또는 최종 보고서가 필요하면 `.agent-context/`를 확인합니다. 설치 프로그램은 다음 OpenCode 구성 파일만 기록합니다: ```text <OpenCode config>\plugins\opencode-plusplus.js <OpenCode config>\agents\opencode-plusplus.md <OpenCode config>\opencode-plusplus\state.json <OpenCode config>\opencode-plusplus\installation.json ``` 이전 버전에서 슬래시 명령을 생성하거나 `app.asar`를 패치한 파일을 제거합니다. 더 이상 OpenCode Desktop 번들을 변경하지 않습니다. 기본 구성 디렉터리는 `%USERPROFILE%\.config\opencode`이며 `OPENCODE_CONFIG_DIR`가 우선합니다. ## 보고 및 경계 런타임 증거는 각 저장소에 로컬입니다: - `.agent-context/traces/`는 실행 및 테스트 증거를 포함; - `.agent-context/runs/`는 작업 컨텍스트와 편집 경계를 포함; - `.agent-context/loops/`는 결정과 수렴 상태를 포함; - `.agent-context/sidecar/latest.md`는 최신 검증 요약을 포함. - `.agent-context/sidecar/visualization.json`은 최신 구조화된 Harness 대시보드 스냅샷을 포함. 플러그인은 운영체제 샌드박스가 아닙니다. 다른 애플리케이션이 파일을 편집하는 것을 막을 수 없고, 종료 코드로 비즈니스 의미를 증명할 수 없으며, 불투명한 도구 매개변수가 올바르게 분류된다고 보장할 수 없습니다. 명령 통과는 증거이지 완전한 정확성 증명이 아닙니다. 차단 결과는 선택한 모드가 수정하거나 인간 검토를 요청하도록 요구합니다. ### 사용자가 보는 것 데스크톱 도구 결과는 기본적으로 간결한 `OpenCode++ ✓ Verified`, `✗ Repair required` 또는 `⚠ Human review` 상태입니다. 구조화된 JSON에는 여전히 `observed`, `prevented`, `requested`, `repaired`, `verified` 및 `unresolved` 항목을 포함하는 `actionSummary`가 있습니다. `opencode_plusplus_dashboard`를 호출하면 결정 근거, 증거 신선도, 개입 카운트 및 선택/거부된 파일을 포함한 전체 `Plan -> Prepare -> Retrieve -> Execute -> Collect -> Evaluate -> Decide -> Persist -> Finalize` 뷰를 볼 수 있습니다. 대시보드는 기록된 시스템 사실과 결정 입력을 노출합니다. 숨겨진 모델 사고 연쇄는 노출하지 않습니다. 이는 사적인 내부 추론을 감사 가능한 사실로 제시하지 않으면서 디버깅과 검토에 유용한 뷰를 만듭니다. 데스크톱 결과와 `.agent-context/sidecar/latest.md`는 다음 문제를 구분합니다: - **개입 파일:** 검사 선택, 경계 내 편집 또는 이유와 함께 거부된 파일; - **차단된 위험:** 안전하지 않은 명령, 보호된 경로, 오래된 컨텍스트, 누락된 테스트, 정책 위반 또는 미해결 회귀; - **제안된 수정:** 요청된 작업 또는 실행기가 보고한 편집이지만 여전히 증거가 필요; - **검증된 수정:** 수정 후 현재 작업 트리에 대한 새로운 명령 또는 CI 증거가 뒤따름; - **인간 작업:** 미해결 발견, 반복되는 무진전 상태 또는 Harness가 증명할 수 없는 의미 결정. 따라서 `verified fix`는 `suggested fix`보다 좁습니다. 주석, 컨텍스트 문서, 수동 선언, 성공한 초기 테스트, 소스 코드 편집, 커밋 목록 또는 모델 생성 요약은 그럴듯해 보인다는 이유만으로 검증된 것이 될 수 없습니다. 외부 컨텍스트는 신뢰할 수 없는 지침이고, 주석은 로컬 지식이지 정책이 아닙니다. 결과가 `human-review`를 표시하면 `actionSummary.evidence`에서 정확히 누락된 증거를 읽으십시오. 이는 작업을 반복하라는 요구가 아닙니다. 컨텍스트 캐시 및 레지스트리 사용은 `.agent-context/cache/` 및 `.agent-context/context-registry/usage/` 아래에 저장됩니다. 로컬 피드백은 `.agent-context/context-registry/feedback/` 아래에, 주석은 `.agent-context/knowledge/annotations/` 아래에, 개입 기록은 `.agent-context/interventions/` 아래에 저장됩니다. 이들은 로컬 런타임 아티팩트이며 일반적으로 커밋하지 않은 상태로 두어야 합니다. Windows에서 공백과 비ASCII 문자가 포함된 경로가 지원되지만, 플러그인은 여전히 활성 사용자의 권한, 저장소 쓰기 가능성 및 OpenCode Desktop이 구성된 플러그인 디렉터리를 로드하는지에 의존합니다. 바이러스 백신 잠금, 읽기 전용 폴더, 사용할 수 없는 네트워크 소스, 유효하지 않은 레지스트리 내용 및 권한 실패는 진단 또는 인간 검토 상태로 보고되며, 성공적인 검증으로 변환되지 않습니다. ## Harness 사용자 정의 OpenCode++는 의도적으로 확장 지점입니다. OpenCode가 너무 관대하거나 너무 엄격하거나 팀 워크플로에 맞지 않는다면, 문제를 프롬프트에 숨기지 말고 플러그인을 포크하거나 확장하여 자체 Harness 정책을 정의하십시오. 유용한 사용자 정의 지점은 다음과 같습니다: - `src/installer/opencode-plusplus-prompts.ts`의 기본 에이전트 프롬프트; - `src/integrations/opencode/plugin-runtime/`의 명령 및 보호 경로 규칙; - `src/retrievers/` 및 `src/core/ranker.ts`의 검색 순위; - `src/outputs/evidence.ts` 및 `src/harness/verification-plane/`의 증거 신뢰 및 신선도; - `src/harness/control-plane/`의 루프 중지 및 결정 중재; - `src/integrations/opencode/plugin-runtime/harness/`의 데스크톱 특정 도구 동작. 안전한 사용자 정의 패턴은 다음과 같습니다: 필요한 정책에 대한 테스트를 추가하고, 플러그인 또는 에이전트 모드를 변경하고, 전체 검사를 실행하고, 체크섬이 있는 새 Windows 설치 프로그램을 배포합니다. Harness가 무엇을 관찰할 수 있고 무엇이 여전히 인간 결정인지 명확히 하십시오. ## 기여 1. 저장소를 포크하고 집중된 브랜치를 만듭니다. 2. `AGENTS.md`, 관련 소스 파일 및 일치하는 중영문 문서를 읽습니다. 3. 동작을 변경하기 전에 결정론적 테스트를 추가하거나 업데이트합니다. 4. 데스크톱 런타임 아티팩트, `dist/`, 설치 프로그램 스테이징, 키 및 로컬 `.agent-context/` 파일을 커밋하지 않도록 유지합니다. 5. `npm run check`, `npm run lint`, `npm run format:check`, `npm run docs:bilingual:check` 및 `npm test`를 실행합니다. 6. 설치 프로그램 변경의 경우 Windows에서 `npm run build:installer:windows`, `npm run test:installer:windows` 및 `npm run release:verify`도 실행합니다. 7. 사용자 문서의 두 언어 버전을 업데이트하고 풀 리퀘스트에서 호환성 경계를 설명합니다. ## 개발자 호환성 표면 저장소는 소스 개발, CI, 진단 및 호환성 통합을 위한 CLI 및 MCP 진입점을 유지합니다. 이들은 정상 데스크톱 설치 경로가 아니며 일반 사용자에게는 필요하지 않습니다. ## 라이선스 MIT