2nd/10_Wiki/Topic_Programming/Architecture/AstraAI_아키텍처_개요.md

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

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
astraai-architecture-overview	AstraAI 아키텍처 개요	Architecture	draft	applied		Astra AstraAI feature-based architecture 전체 구조 모듈 아키텍처 제2뇌 OS		S	0.95	2026-06-13	2026-06-13			architecture astraai feature-based layering overview	AstraAI/src/extension.ts AstraAI/src 트리(308 TS 파일) AstraAI/package.json AstraAI/src/core/services.ts	AstraAI

AstraAI 아키텍처 개요

🎯 한 줄 통찰 (One-line insight)

AstraAI(Astra)는 "로컬 LLM 을 두뇌로 쓰는 VS Code 확장형 자기진화 지식 OS"이며, 기능별 폴더 경계 + 얇은 entry point + 핵심 인프라(core) 위에 도메인(features)을 쌓는 계층형 모듈 아키텍처로 308개 파일을 조직한다 [S1][S2].

🧠 핵심 개념 (Core concepts)

1. Feature-based 구조: src/features/ 아래 각 폴더가 독립 기능(stocks, calendar, company, datacollect, devilAgent…). 기능 간 결합을 최소화하고, 공통 인프라만 core//lib/ 에서 공유 [S2].
2. 계층 분리: core(인프라) → lib/memory/retrieval/intelligence(역량) → features(기능) → extension.ts(조립). 아래 계층은 위를 모른다 [S2].
3. 얇은 entry point: extension.ts 의 activate() 는 조립과 등록만 한다 — 객체 생성, 의존성 주입, 명령 등록, 워처 시작. 로직은 전부 모듈에 위임 [S1].
4. 의존성 주입: 생성자에 옵션 객체로 협력자를 주입(new AgentExecutor(context, { lmStudioStreamer, approvalQueue, ... })) — 테스트·교체 용이 [S1].
5. 싱글톤 인프라: 프로세스 전역이 자연스러운 자원(lockManager, actionQueue)은 모듈 싱글톤으로 export [S1].

🧩 추출된 패턴 (Extracted patterns)

• God-class 분해: 거대해지는 orchestrator(agent.ts)를 handlePrompt/, llm/, actions/, multiAgent/, sessions/ 하위 모듈로 쪼개 함수 단위로 추출하고, orchestrator 는 이들을 호출만 한다 [참조: Agent 오케스트레이터 분해].
• 인터페이스 우선 서비스: IAIService/IBrainService 인터페이스를 두고 구현(AIService)을 분리 — 엔진 폴백 같은 정책을 구현체에 캡슐화 [S3].
• 자기등록 핸들러: slashRouter 에 핸들러가 side-effect import 로 자기 등록 — 새 명령 추가 시 중앙 등록표를 건드리지 않음 [S1].
• 부트스트랩 분리: 활성화 시 필요한 초기화(brain 디렉터리, 임베딩 감지, 기능 인벤토리)를 extension/*Bootstrap.ts 로 분리해 entry point 를 얇게 유지 [S1].
• disposable 수명 관리: 생성한 모든 자원을 context.subscriptions.push(...) 로 등록해 확장 종료 시 일괄 정리 [S1].

📖 세부 내용 (Details)

디렉터리 지도 (역할별)

• core/ — 횡단 인프라: lock, queue, transaction, errors, errorHandler, services(AI/Brain 서비스), session, events, health, telemetry, statusBar.
• memory/ — 5계층 인지 메모리(Short/Long/Project/Procedural/Episodic) + distillation. → 5계층 메모리 시스템.
• retrieval/ — RAG 파이프라인: chunker, scoring(TF-IDF), embeddings, brainIndex, contextBudget, rerank 류. → RAG 검색 파이프라인.
• intelligence/ — 검증·자기평가: criticAgent, confidenceEngine, correctionLoop, epistemicGuardBlock, knowledgeValidation. → Intelligence 검증 레이어.
• lib/contextBuilders/ — 프롬프트에 들어갈 컨텍스트 블록을 조립하는 순수 함수 모음(메모리·프로젝트·일정·자기인식 등 30+개).
• features/ — 도메인 기능. 각자 index.ts(공개 API) + store + handler + prompt 로 구성되는 경향.
• agent/ + agents/ — 에이전트 실행 세부와 다중 에이전트 워크플로 매니저.
• integrations/ — 외부 연동(telegram).
• sidebar/ + sidebarProvider.ts — 웹뷰 UI 와 메시지 핸들러.
• system/, lmstudio/, scaffolder/, skills/ — 시스템 사양 탐지, LM Studio SDK 수명관리, 프로젝트 스캐폴딩, 스킬 로딩.

제어 흐름 (한 턴의 처리)

1. 웹뷰(사이드바)에서 사용자 입력 → sidebar/chatHandlers → AgentExecutor.
2. agent/handlePrompt/* 가 컨텍스트 블록(메모리·RAG·프로젝트·일정)을 조립.
3. 모델 라우팅: 클라우드 prefix 면 provider 어댑터, 아니면 로컬 엔진(LM Studio/Ollama). → LLM 프로바이더 추상화.
4. 스트리밍 응답 → 후처리(sanitize, devil rebuttal) → post-answer hooks(critic 검수, 교정 캡처).
5. 세션 종료 시 메모리 추출/증류, 성장 사이클 워처가 폐루프로 학습.

빌드/런타임

• esbuild 단일 번들(out/extension.js), vscode external. 런타임 의존성은 @lmstudio/sdk, pdf-parse 둘뿐 — 나머지는 native API(fetch 등)로 자급 [S2].

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

• 단일 거대 agent.ts(1681줄): 분해를 했음에도 orchestrator 가 여전히 크다. 이는 "한 턴의 제어 흐름을 한 곳에서 읽을 수 있게" 하려는 의도적 트레이드오프 — 세부는 추출하되 흐름의 골격은 남긴다.
• features 간 결합: 일부 기능(company, stocks)은 텔레그램·시트 등 여러 통합을 동시에 참조해 완전 독립은 아니다. core/lib 를 통한 간접 결합으로 완화.

🛠️ 적용 사례 (Applied in summary)

• AstraAI/src/extension.ts 의 activate() 전체가 "얇은 조립 entry point" 의 교과서적 예 — 25개+ 모듈을 생성·주입·등록하지만 비즈니스 로직은 0 [S1].

💻 코드 패턴 (Code patterns)

// activate(): 조립과 등록만 — 로직은 모듈에 위임 (src/extension.ts 발췌)
export async function activate(context: vscode.ExtensionContext) {
    await ensureDefaultBrainConfigured();          // 부트스트랩 분리
    void ensureEmbeddingConfigured(context);       // 비차단 best-effort
    initAstraPathResolver(context);

    const lmStudioClient = new LMStudioClient(getConfig().ollamaUrl);
    const agent = new AgentExecutor(context, {     // 생성자 의존성 주입
        onStreamLifecycle: { start: () => lifecycle.onStreamStart(), end: () => lifecycle.onStreamEnd() },
        lmStudioStreamer, approvalQueue,
    });
    const provider = new SidebarChatProvider(context.extensionUri, context, agent, { lifecycle, /* ... */ });

    context.subscriptions.push(                     // 수명 관리: 종료 시 일괄 dispose
        vscode.commands.registerCommand('g1nation.openChat', () => provider.openAsPanel(vscode.ViewColumn.Three)),
        ...registerProviderCommands(context, { getProvider: () => provider }),
    );
}

🔗 지식 그래프 (Knowledge Graph)

• 상위/루트: AstraAI 아키텍처 개요
• 관련 개념: VSCode 확장 구조와 생명주기, 의존성 주입과 서비스 인터페이스, Agent 오케스트레이터 분해, 모듈 시스템과 프로젝트 구성
• 참조 맥락: 로컬 LLM 이 새 기능을 "어느 계층/폴더에 어떤 형태로" 추가할지 판단할 때 최상위 지도로 참조.

📚 출처 (Sources)

• [S1] AstraAI/src/extension.ts — activate/deactivate, 조립·주입·등록·부트스트랩
• [S2] AstraAI/src 디렉터리 트리(308 TS 파일) + package.json — 계층/번들 구성
• [S3] AstraAI/src/core/services.ts — IAIService/IBrainService 인터페이스 우선 설계

📝 변경 이력 (Change history)

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