81 lines
5.0 KiB
Markdown
81 lines
5.0 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] rejectAgentStep / !stop — AG 미등록 커맨드 + 렌더러 전용 함수 + 스테일 프리미티브
|
|
- **증상**: `!stop` 명령이 AI를 멈추지 못함. 로그: "No active cascade" / "no session tracked yet"
|
|
- **원인**: (1) `antigravity.agent.rejectAgentStep`은 AG 미등록 커맨드. (2) 대체한 `getActiveCascadeId()`는 **렌더러(DOM) 전용 함수** — Extension host에서 항상 `undefined` 반환. (3) **v0.4.5 수정도 실패**: `extension.ts`의 `getActiveSessionId: () => activeSessionId`가 module-level 스트링 프리미티브를 참조 — step-probe가 `ctx.activeSessionId`를 업데이트해도 extension.ts의 변수는 불변 (프리미티브 복사)
|
|
- **해결** (2026-03-18 v0.4.6): `step-probe.ts`에서 `getActiveSessionId()` getter 함수 export → extension.ts closures에서 `getStepProbeSessionId()` 호출. 이제 step-probe의 live `ctx.activeSessionId`를 직접 읽음 (`ab0c116`)
|
|
- **주의**: JS에서 **string/number는 프리미티브라 참조 전달 불가** — 객체 속성을 공유하려면 getter 함수나 객체 래퍼 사용 필수
|
|
- **Vikunja**: #411, #410
|
|
|
|
### [2026-03-19] browser_subagent RPC 매핑 — 잘못된 interactionPayload
|
|
- **증상**: 서브 에이전트의 "Allow" (execute JavaScript on localhost) 버튼이 자동 승인되지 않음
|
|
- **원인**: `step-probe.ts`에서 `browser_subagent` toolName이 분류 없이 raw toolName으로 전달 → `approval-handler.ts`의 RPC 매핑에서 `runExtensionCode`가 아닌 default `runCommand` payload로 전송됨
|
|
- **해결** (v0.5.1): `step-probe.ts`에 `browser_subagent`/`open_browser_url` 분류 추가 + `approval-handler.ts` L384에 `browser_subagent` 조건 추가
|
|
- **주의**: 새 tool type 추가 시 반드시 step-probe 분류 + approval-handler RPC 매핑 + observer-script PATS 3곳 모두 확인
|
|
|
|
---
|
|
|
|
> [!NOTE]
|
|
> v0.4.5 수정 사항(Hub pending_owners, diff_review WS, auto_approve 이중쓰기, WS dual-write, ApprovalView fallback)은
|
|
> 코드 수정 완료됨. E2E 통합 검증은 Vikunja #410에서 추적 중.
|
|
|
|
---
|
|
|
|
## 핵심 작업 규칙 (과거 이슈에서 반복된 패턴)
|
|
|
|
> 아래는 과거 이슈에서 반복적으로 나타난 패턴을 규칙으로 정리한 것입니다.
|
|
|
|
| # | 규칙 | 관련 이슈 (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 |
|
|
| 11 | **HttpBridgeContext에 프리미티브 by-value 복사 금지** — 별도 객체 생성 시 getter 사용 | HttpBridgeContext stale primitive |
|