Files

T

Antigravity Agent e2c5471046 wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-16 09:55:38 +09:00

7.6 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

모듈 시스템과 프로젝트 구성

🎯 한 줄 통찰 (One-line insight)

모듈 시스템은 "무엇을 공개하고(export) 무엇을 가져올지(import)"로 코드 경계를 긋는 것이며, AstraAI 는 barrel(index.ts) 재수출·side-effect import 자기등록·동적 import 지연로딩을 조합해 308개 파일을 esbuild 단일 번들로 묶는다 [S1][S4].

🧠 핵심 개념 (Core concepts)

ES Module 문법: import { x } from './m' / export function x(). TypeScript 는 이 문법을 쓰고, tsconfig module: commonjs 로 CommonJS 로 컴파일된다 [S5].
named vs default export: AstraAI 는 거의 전부 named export 만 쓴다 — 자동완성·일관된 이름·리팩터링 안전성 때문. default export 는 사실상 배제 [S2].
Barrel 파일 (index.ts): 하위 모듈을 한 곳에서 재수출(export * from './types')해 외부가 깔끔한 진입점 하나만 import 하게 한다 [S2][S3].
Side-effect import: import './features/teamops/handlers' — 값을 가져오지 않고 모듈 로드의 부수효과(핸들러 자기등록)만 노린다 [S1].
Dynamic import (await import(...)): 무겁거나 드물게 쓰는 모듈을 실제 호출 시점에 지연 로딩 — 활성화 시간 단축 [S1].
번들링 (esbuild): 모든 모듈을 out/extension.js 하나로 묶되 vscode 는 external (런타임 제공) [S4].

🧩 추출된 패턴 (Extracted patterns)

상대경로 import + 명확한 트리: ../config, ./types 같은 상대경로로 모듈을 참조하고, 폴더 구조가 곧 도메인 경계(features/, core/, memory/, retrieval/, intelligence/).
barrel 재수출로 진입점 단일화: src/memory/index.ts 가 5개 메모리 클래스 + distillation API + export * from './types' 를 한 번에 노출 [S3].
side-effect import 로 핸들러 자기등록: entry point 가 import './features/system/handlers' 만 하면 그 모듈이 slashRouter 에 자기를 등록 — 등록 코드를 한 곳에 모으지 않는 분산 등록 [S1].
동적 import 로 무거운 기능 지연: const { runDatacollectSetup } = await import('./features/setup/datacollectSetup') — 명령 실행 시에만 로드 [S1].
타입 전용 import: import type { ChatMessage } from '../../agent' — 컴파일 후 사라지는 타입만 가져와 순환참조·번들 부담 회피 [S6].

📖 세부 내용 (Details)

폴더 = 도메인 경계

src/
  core/         공통 인프라 (lock, queue, transaction, errors, services, events)
  features/     기능 도메인 (각 폴더가 독립 기능: stocks, calendar, company, datacollect…)
  memory/       5계층 메모리
  retrieval/    RAG 검색
  intelligence/ 검증·자기평가 (critic, confidence, correctionLoop)
  lib/          순수 헬퍼 + contextBuilders (프롬프트 컨텍스트 조립)
  agent/        에이전트 실행 세부 (handlePrompt/, llm/, actions/, multiAgent/)

각 폴더 안에 index.ts(barrel)가 있으면 외부는 그 하나만 import 한다.

import 순서·스타일

실제 코드는 (1) Node 표준(fs, path), (2) vscode, (3) 내부 모듈 순으로 import 하며, 내부는 도메인별로 묶어 가독성을 유지한다. 거대한 orchestrator(agent.ts)는 import 가 100줄을 넘는데, 이는 기능을 작은 모듈로 추출하고 다시 끌어모으는 구조의 자연스러운 결과다 [S1].

side-effect import 의 순서 민감성

// slashRouter 가 먼저 로드된 뒤 핸들러가 자기 등록되도록 entry point 에서 import
import './features/teamops/handlers';
import './features/system/handlers';
import './features/datacollect/handlers';

주석이 "왜 여기서 import 하는지"(로드 순서 보장)를 명시한다 — side-effect import 는 순서가 동작에 영향을 주므로 의도를 적는 것이 필수 [S1].

번들/빌드

compile: esbuild src/extension.ts --bundle --platform=node --external:vscode --outfile=out/extension.js — 단일 파일 번들 [S4].
watch: tsc -watch (타입 체크용), test: jest. 런타임 의존성은 @lmstudio/sdk, pdf-parse 둘뿐이고 axios 대신 native fetch 사용 [S4].

⚖️ 모순 및 업데이트 (Contradictions & updates)

barrel 의 양날: index.ts 재수출은 진입점을 깔끔히 하지만, 과하면 순환참조와 "한 줄 import 가 거대한 그래프를 끌어옴" 문제를 낳는다. AstraAI 는 무거운 기능을 동적 import 로 분리해 이를 완화 [S1].
commonjs vs ESM: tsconfig 는 commonjs 로 컴파일하지만 소스는 ESM 문법으로 작성한다 — VS Code 확장 런타임(Node)이 CJS 를 기대하기 때문. 새 프로젝트라면 ESM 출력도 가능하나 호환성 고려 필요 [S5].

🛠️ 적용 사례 (Applied in summary)

AstraAI/src/extension.ts — side-effect import, 동적 import, 100+줄 named import 의 실제 예 [S1].
AstraAI/src/memory/index.ts, src/retrieval/index.ts — barrel 재수출 [S2][S3].

💻 코드 패턴 (Code patterns)

// 1) side-effect import — 핸들러 자기등록 (순서 주석 필수) (src/extension.ts)
import './features/teamops/handlers';
import './features/system/handlers';

// 2) barrel 재수출로 진입점 단일화 (src/memory/index.ts)
export { ShortTermMemory } from './ShortTermMemory';
export { LongTermMemory } from './LongTermMemory';
export * from './types';

// 3) 동적 import 로 무거운 기능 지연 (src/extension.ts)
vscode.commands.registerCommand('g1nation.setupDatacollect', async () => {
    const { runDatacollectSetup } = await import('./features/setup/datacollectSetup');
    await runDatacollectSetup();
});

// 4) 타입 전용 import — 런타임 부담/순환참조 회피
import type { AgentExecutorOptions, ChatMessage } from '../../agent';

✅ 검증 상태 및 신뢰도

상태: draft
검증 단계: applied
출처 신뢰도: A
신뢰 점수: 0.92
중복 검사 결과: 신규 생성 (New discovery)

🔗 지식 그래프 (Knowledge Graph)

상위/루트: TypeScript 기초와 타입 시스템
관련 개념: AstraAI 아키텍처 개요, VSCode 확장 구조와 생명주기, 코딩 컨벤션과 주석 철학
참조 맥락: 로컬 LLM 이 파일을 나누고 import/export 를 구성할 때 참조.

📚 출처 (Sources)

[S1] AstraAI/src/extension.ts — side-effect/동적 import, named import 구성
[S2] AstraAI/src/features/providers/index.ts — named export, 재수출
[S3] AstraAI/src/memory/index.ts, src/retrieval/index.ts — barrel(export *) 패턴
[S4] AstraAI/package.json — esbuild 번들 스크립트, 의존성
[S5] AstraAI/tsconfig.json — module/target 설정
[S6] AstraAI/src/agent/multiAgent/workflow.ts — import type

📝 변경 이력 (Change history)

2026-06-13: AstraAI 코드 분석 기반 초안 생성.

7.6 KiB Raw Blame History