connectai/docs/plans/web-fetch-and-mode-parity-plan.md

웹 접근 + 모드 동등성 수정 계획 (v2 — 적대적 리뷰 + 재검증 반영)

v1 → v2 핵심 변화: 근본 원인 재진단

리뷰 과정에서 일반 챗에는 URL 주입 기능이 이미 존재함이 확인됨 (src/lib/contextBuilders/urlContext.ts, agent.ts:557-569에서 호출).

그런데 왜 실패했나 (정확한 원인)

1. 일반 챗: buildUrlContext가 Datacollect Bridge(127.0.0.1:3002)에 100% 의존. 확장은 Bridge를 자동 시작하지 않음 → Bridge 꺼져 있으면 '접근 실패' 정직 블록 → 모델이 "사이트 방문 불가"라고 답함. (Bridge 추출 실패/JS 렌더링 페이지도 동일)
2. 기업 모드: dispatcher 경로에 URL 주입이 아예 없음 → 항상 불가.
3. 검증 완료된 사실:
   • isCasualConversation 게이트는 40자 초과 프롬프트에 영향 없음 (문제 아님)
   • buildRequestHistory는 internal 메시지를 필터링하지 않음 → internal push가 LLM에 도달
   • continuation loop 트리거 = "action이 chatHistory를 늘렸는가" (agent.ts:1238) → read_file과 동일 패턴이면 fetch_url도 자동 재분석
   • _handleCompanyCasual은 일반 챗 경로(_handlePrompt)를 타므로 별도 처리 불필요
   • BASE_SYSTEM_PROMPT/DispatcherDeps를 단언하는 기존 테스트 없음 (안전)

---

수정 설계 (v2)

A. 신규 src/features/web/webFetch.ts — Bridge 무관 직접 fetch (vscode 의존 없음)

export function extractUrls(text: string, max = 2): string[]
// http(s)만, dedupe, trailing 구두점 제거, 슬래시 명령(/...)으로 시작하면 빈 배열

export interface WebFetchResult { ok: boolean; url: string; title: string; text: string; error?: string }
export async function fetchUrlDirect(url: string, opts?: { timeoutMs?: number /*15s*/; maxChars?: number /*20000*/ }): Promise<WebFetchResult>
// global fetch (bridgeClient가 이미 사용 — 호스트 지원 확인됨) + typeof 가드
// AbortController timeout / html이면 script·style·noscript 제거 → 태그 strip →
// 엔티티 최소 디코드 → 공백 정리 + <title> 추출 / html 아니면 raw cap / throw 금지

B. urlContext.ts 개선 — Bridge → 직접 fetch 폴백 (기존 인터페이스 유지)

• buildUrlContext(url): ① Bridge /api/web-extract 시도 (타임아웃 45s→15s 단축) → ② 실패/빈 본문이면 fetchUrlDirect 폴백 → ③ 둘 다 실패 시 기존 정직 블록
• 모듈 레벨 TTL 캐시 (URL→블록, 5분, 최대 10개) — chat/alignment/dispatcher가 같은 URL을 연달아 요청해도 네트워크 1회
• extractUrlFromPrompt는 유지하되 호출부는 extractUrls(최대 2개)로 확장
• 실패 안내 문구에서 "브리지 실행 확인" → "직접 접속도 실패" 반영

C. <fetch_url> 액션 태그 (LLM 주도 — 양 모드 광고)

• 신규 src/agent/actions/webFetch.ts: <fetch_url url="..."/> (회당 최대 2개)
  • fileDeleteRead.ts의 read_file 패턴 복제: regex → buildUrlContext(url) → ctx.report.push('🌐 Fetched: <url>') + ctx.chatHistory.push({role:'system', internal:true})
  • chatHistory push → 일반 챗 continuation loop 자동 트리거 (검증됨)
  • transactionManager 불필요 (read-only)
• agent.ts executeActions에 applyWebFetchActions(ctx) 등록 (listFiles 다음)
• utils.ts BASE_SYSTEM_PROMPT: [ACTION 15: FETCH URL] — 라인 401 부근, 기존 포맷 준수 ("링크의 실제 내용이 필요할 때만, 일반 지식 질문에는 사용 금지" 지침 포함)
• promptBuilder.ts specialist 액션 목록(129-142)에 fetch_url 추가

D. 기업 모드 — DispatcherDeps에 2개 별도 필드 (리뷰 권고 반영)

// dispatcher.ts DispatcherDeps에 추가:
architectureContextBlock?: string;  // 현재 워크스페이스 아키텍처 (문제 2 해소)
webContextBlock?: string;           // 사용자 프롬프트 URL pre-fetch 결과

• 4개 합성 지점(planner ~358, specialist ~671, verifier ~699, inspector/CEO ~1053)에서:

  const prefix = [deps.architectureContextBlock, deps.webContextBlock, contract...]
      .filter(Boolean).join('\n\n');
  

  contract 앞에 배치 (둘 다 optional — 미전달 시 기존 동작 100% 동일)
• _runCompanyTurn(sidebarProvider:2189) deps 빌드 시:
  • architectureContextBlock = this._buildProjectArchitectureContext() 6,000자 절단
  • webContextBlock = extractUrls(userPrompt) → buildUrlContext (캐시 적중) → 8,000자 cap
  • 빌드는 try/catch — 실패해도 turn 진행

E. Alignment 웹 컨텍스트

• _runIntentAlignment 첫 라운드: URL 있으면 buildUrlContext(캐시) 결과를 기존 projectContext 입력에 append (합계 3,000자 cap 유지 — web 부분은 별도 2,000자 cap 후 합산이 아니라, arch 먼저 + web 이어붙이고 총 5,000자로 상향)
• 효과: "그 사이트가 뭐냐"는 alignment 질문 차단

F. config + package.json

• webAutoFetchEnabled: boolean 기본 true — g1nation.web.autoFetchUrls (pre-fetch 게이트: 일반 챗 주입부 + _runCompanyTurn + alignment 모두 이 키 확인. 기존 일반 챗 주입부에도 게이트 추가 — 현재는 무조건 실행)

---

구현 순서

1. src/features/web/webFetch.ts 신규 + tests/webFetch.test.ts
2. urlContext.ts 폴백 + 캐시 + 타임아웃 단축
3. config.ts + package.json 키
4. src/agent/actions/webFetch.ts + agent.ts 등록 + BASE_SYSTEM_PROMPT + promptBuilder
5. dispatcher.ts deps 2필드 + 4지점 합성
6. sidebarProvider.ts: _runCompanyTurn + _runIntentAlignment
7. agent.ts 일반 챗 주입부: extractUrls(2개) + config 게이트
8. npx tsc --noEmit + npm test

리스크 (v2)

리스크	완화
Bridge 타임아웃 45→15s 단축으로 느린 추출 실패 ↑	직접 fetch 폴백이 받아줌 (총 최대 ~30s)
EUC-KR 등 비UTF-8 직접 fetch 깨짐	Bridge 우선 경로가 1차 방어, 한계 문서화
거대 페이지 토큰 폭주	직접 20,000자 / 기업 블록 8,000자 / alignment 총 5,000자 cap
dispatcher 테스트 파손	신규 필드 optional — 미전달 시 기존과 동일
캐시 오염 (실패 결과 캐시)	실패 블록은 캐시하지 않음 — 성공 결과만 TTL 캐시
LLM의 fetch_url 남발	회당 최대 2개 처리 + "필요할 때만" 프롬프트 지침