113 lines
6.9 KiB
Markdown
113 lines
6.9 KiB
Markdown
# Known Issues & Lessons Learned
|
|
|
|
> **이 파일은 SSOT(Single Source of Truth)입니다.**
|
|
> 디버깅이나 구현 전에 **반드시** 이 파일을 확인하세요.
|
|
> 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.
|
|
|
|
> [!TIP]
|
|
> 해결 완료된 과거 이슈는 [`known-issues-archive.md`](file:///c:/Users/Variet-Worker/Desktop/gravity_control/.agents/references/known-issues-archive.md)에 보관되어 있습니다.
|
|
> 비슷한 문제가 재발하면 archive에서 검색하세요.
|
|
|
|
---
|
|
|
|
## 포맷
|
|
|
|
```markdown
|
|
### [날짜] [키워드] — 한줄 요약
|
|
- **증상**: 무엇이 잘못되었는가
|
|
- **원인**: 근본 원인
|
|
- **해결**: 올바른 해결 방법
|
|
- **주의**: 재발 방지를 위한 교훈
|
|
```
|
|
|
|
---
|
|
|
|
## 공통 이슈
|
|
|
|
### [2026-03-08] PowerShell curl — Invoke-WebRequest 충돌
|
|
- **증상**: `curl` 명령이 예상과 다른 응답 형식을 반환
|
|
- **원인**: PowerShell에서 `curl`은 `Invoke-WebRequest`의 별칭
|
|
- **해결**: **`curl.exe`**를 명시적으로 사용
|
|
- **주의**: HTTP 관련 모든 명령에서 `curl.exe` 사용 필수
|
|
|
|
### [2026-03-08] PowerShell npm — 실행 정책 오류
|
|
- **증상**: `npm run` 명령이 `실행 정책` 관련 오류로 실패
|
|
- **원인**: PowerShell 스크립트 실행 정책이 제한적
|
|
- **해결**: `cmd /c npm run dev` 형식으로 cmd를 통해 실행
|
|
- **주의**: npm 관련 명령은 항상 `cmd /c` 접두어 사용 권장
|
|
|
|
---
|
|
|
|
## 미해결 이슈
|
|
|
|
### [2026-03-11] fs.watch silent fail — Discord→Extension 명령 전달 불가
|
|
- **증상**: `!auto`, `!stop`, 텍스트 릴레이 등 Discord→Extension 방향 명령이 전부 작동 안 함. Extension log에 `[AUTO]` 로그 0건
|
|
- **원인**: `watchCommandsDir()`의 `fs.watch`가 Windows에서 silent fail. watcher 세팅은 되지만 이벤트가 실제로 fire 안 됨
|
|
- **해결**: `fs.watch` 유지 + 3초 `setInterval` 폴링 fallback 추가. `processAllCommands()` 함수로 공통화
|
|
- **주의**: `fs.watch`는 Windows에서 구조적으로 불안정. **새 watcher 추가 시 반드시 polling fallback 병행**
|
|
|
|
### [2026-03-11] rejectAgentStep — AG 미등록 VS Code 커맨드
|
|
- **증상**: `/stop` 및 거부 시 `antigravity.agent.rejectAgentStep` → `command not found`
|
|
- **원인**: AG IDE가 이 커맨드를 런타임에 등록하지 않음
|
|
- **해결**: **미해결** — AG가 실제 등록하는 커맨드 목록 조사 후 올바른 커맨드로 교체 필요
|
|
- **주의**: AG 런타임 커맨드 미등록 문제의 근본 원인 (archive 참조: `[2026-03-09] VS Code Accept`)
|
|
|
|
### [2026-03-16] pending 파일 무한 누적 — Collector/Bot이 로컬 파일 삭제 안 함
|
|
- **증상**: `bridge/pending/` 디렉토리에 56개+ 파일 누적 (auto_resolved + pending)
|
|
- **원인**: `remote` 모드에서 Bot은 서버에서 동작하여 로컬 pending 파일 직접 삭제 불가
|
|
- **해결**: **(미완료)** WS Hub 전환으로 파일 기반 IPC 자체가 줄어들면 자연 해소. Collector 정리 로직 일부 추가됨
|
|
- **주의**: WS 연결 상태에서는 pending 파일을 아예 생성하지 않으므로 해당 없음
|
|
|
|
---
|
|
|
|
## 모니터링 중 이슈 (최근 수정, 재발 관찰 필요)
|
|
|
|
### [2026-03-17] Hub pending_owners 생명주기 — WS 재연결 시 승인 응답 소실
|
|
- **증상**: Discord에서 승인 클릭해도 AG Extension에서 아무 동작 안함
|
|
- **원인**: `_disconnect()`에서 Extension 연결 끊기면 `pending_owners[rid]` 삭제 → 재연결 후 owner 정보 소실
|
|
- **해결**: (1) 삭제 대신 같은 project 다른 연결로 재할당, (2) `_register_connection`에서 orphaned pending 재할당, (3) 같은 project 활성 연결 fallback
|
|
- **주의**: Gateway 모드에서 file bridge fallback은 **완전히 무용** — Docker 볼륨에 파일 작성하지만 Extension은 로컬 bridge/ 감시
|
|
|
|
### [2026-03-17] diff_review Accept All WS 경로 regression (v0.4.5 fix)
|
|
- **증상**: Discord에서 Accept all 클릭해도 AG에서 반응 없음
|
|
- **원인**: WS 전환 시 `onResponse` 핸들러에 `diff_review` step_type 분기 누락
|
|
- **해결**: `handleDiffReviewResponse()` export + WS `onResponse`에서 호출
|
|
- **주의**: **WS 경로 추가 시 file-bridge 경로의 모든 분기를 반드시 포팅할 것**
|
|
|
|
### [2026-03-17] _auto_approve_via_hub 이중 쓰기 (v0.4.5 fix)
|
|
- **증상**: auto-approve 시 Extension에 응답이 2번 도착
|
|
- **원인**: Hub WS 전송 후 `return` 없이 file bridge에도 씀
|
|
- **해결**: `if self.hub:` → WS 전송 + `else:` → file bridge. if/else 구조로 변경
|
|
- **주의**: Hub WS와 file bridge는 **항상 상호 배타적**이어야 함
|
|
|
|
### [2026-03-17] WS dual-write — 채팅/승인 이중 발송
|
|
- **증상**: Discord 메시지가 2개씩 도착
|
|
- **원인**: `writeChatSnapshot`/`writePendingApproval`이 WS 전송 후 파일도 동시에 씀
|
|
- **해결**: WS 연결 시 `return`으로 파일 쓰기 건너뛰기
|
|
- **주의**: `writePendingApproval` 수정 시 diff_review metadata 캐싱 + memory dedup 로직이 WS 경로에서도 실행되어야 함
|
|
|
|
### [2026-03-17] ApprovalView Hub 응답 실패 시 silent loss — fallback 없음
|
|
- **증상**: Extension이 pending 생성 후 WS 연결 끊김 → Discord 승인 클릭 → AG에 전달 안 됨
|
|
- **원인**: `ApprovalView`가 Hub 전달 실패 시 file bridge를 건너뜀
|
|
- **해결**: `send_response_to_pending_owner()` 반환값 확인 → `False`면 file bridge fallback (5곳)
|
|
- **주의**: `send_response_to_pending_owner`는 `pending_owners`에 conn_id가 없으면 `False` 반환. Hub 존재 ≠ 전달 성공
|
|
|
|
---
|
|
|
|
## 핵심 작업 규칙 (과거 이슈에서 반복된 패턴)
|
|
|
|
> 아래는 과거 이슈에서 반복적으로 나타난 패턴을 규칙으로 정리한 것입니다.
|
|
|
|
| # | 규칙 | 관련 이슈 (archive 참조) |
|
|
|---|------|--------------------------|
|
|
| 1 | **Hub WS와 file bridge는 상호 배타적** — `if hub: ws + return` / `else: file` | WS dual-write, _auto_approve 이중 쓰기 |
|
|
| 2 | **WS 경로 추가 시 file-bridge의 모든 분기를 포팅** | diff_review WS regression |
|
|
| 3 | **AG RPC `{}` 응답은 실패로 간주** — 메서드명 틀려도 에러 없이 `{}` 반환 | AcknowledgeCascadeCodeEdit |
|
|
| 4 | **ResolveOutstandingSteps는 CANCEL 동작** — 승인에 절대 사용 금지 | Step probe reject |
|
|
| 5 | **Extension 코드 수정 후 반드시 VSIX 빌드 + AG 풀 재시작** | Extension 버전 미배포 |
|
|
| 6 | **HTML 패치 변경 시 V8 CachedData 삭제 필수** | V8 CachedData, CSP |
|
|
| 7 | **`bridge/pending/` 조작 시 반드시 `project_name` + `conversation_id` 필터** | 크로스 프로젝트 DEDUP MERGE |
|
|
| 8 | **`processResponseFile` 상태 리셋은 `sawRunningAfterPending=true`만** | processResponseFile 무한 루프 |
|
|
| 9 | **fs.watch Windows 불안정 — 반드시 polling fallback 병행** | fs.watch silent fail |
|
|
| 10 | **diff_review는 VS Code 커맨드만 유효** — RPC 3개 전략 모두 실패 확정 | diff_review RPC dead-end |
|