reinforce: create wiki documents for autonomous engine architecture and resilience audit
This commit is contained in:
Antigravity Agent
@@ -1,6 +1,7 @@
|
||||
# Index: .
|
||||
|
||||
## 📁 Subcategories
|
||||
- Projects
|
||||
- Topics
|
||||
- Topics_Meeting
|
||||
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
id: datacollector-mac-engine-audit-2026-05-11
|
||||
title: Datacollector_MAC Engine Audit (2026-05-11)
|
||||
category: 10_Wiki/Projects
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [엔진 안정성 감사 리포트, Datacollector Resilience Audit]
|
||||
source_trust_level: A
|
||||
confidence_score: 1.0
|
||||
created_at: 2026-05-11
|
||||
updated_at: 2026-05-11
|
||||
last_reinforced: 2026-05-11
|
||||
verification_status: validated
|
||||
applied_in:
|
||||
- path: /Volumes/Data/project/Antigravity/Datacollector_MAC/src/lib/engine.ts
|
||||
- path: /Volumes/Data/project/Antigravity/Datacollector_MAC/src/lib/diagnostics.ts
|
||||
tags: [audit, datacollector, resilience]
|
||||
---
|
||||
|
||||
# [[Datacollector_MAC Engine Audit (2026-05-11)]]
|
||||
|
||||
## 📌 감사 개요
|
||||
|
||||
`Datacollector_MAC` 프로젝트의 핵심 엔진(`engine.ts`)과 진단 레이어(`diagnostics.ts`)의 실제 코드를 전수 조사하여, 자율 에이전트의 안정성과 결함 허용 능력을 평가한 기록입니다.
|
||||
|
||||
## 📖 감사 결과 (Grounded Findings)
|
||||
|
||||
### 1. 이미 구현된 강점
|
||||
- **영속성 기반 복구**: Zustand `persist` 미들웨어를 통해 큐와 상태가 로컬 스토리지에 보존됨. 브라우저 종료 후 재기동 시 `paused` 상태에서 안전하게 재개 가능함.
|
||||
- **다단계 장애 복구**: 인증 실패 시 자동 Re-auth, 일반 에러 시 3단계 지수 백오프, 치명적 장애 시 백엔드 브릿지 서버 재시작 오케스트레이션이 완비됨.
|
||||
- **결함 격리**: 서킷 브레이커 패턴이 전 API 호출에 적용되어 외부 장애가 엔진으로 전파되는 것을 차단함.
|
||||
|
||||
### 2. 발견된 취약점 및 개선 권고 (Action Items)
|
||||
- **이중 보호 간섭**: 서킷 브레이커와 엔진 백오프 카운터가 독립적으로 작동하여, 서킷 OPEN 시 실제 네트워크 시도 없이 재시도 횟수만 소모되는 현상 발견.
|
||||
- *권고*: 엔진 에러 핸들러에서 `[CIRCUIT OPEN]` 메시지 감지 시 카운터를 소모하지 않고 대기하도록 수정.
|
||||
- **태스크 메타데이터 부족**: 작업 실패 시 어떤 단계(`pipelineStage`)에서 실패했는지가 큐 아이템에 구조화되어 저장되지 않음.
|
||||
- *권고*: `QueueItem` 인터페이스에 `lastFailure` 객체 추가.
|
||||
- **Watchdog 수동성**: 현재 Watchdog(`kickIfStalled`)이 외부 트리거에 의존함.
|
||||
- *권고*: 엔진 기동 시 `setInterval` 기반의 자동 Watchdog 활성화.
|
||||
|
||||
## 💻 적용된 지식 모델
|
||||
|
||||
- [[System_Resilience_and_Fault_Tolerance]]
|
||||
- [[Autonomous_Queue_Processing_Engine]]
|
||||
|
||||
## 🧪 검증 결과
|
||||
|
||||
- **정보 상태:** validated
|
||||
- **검증 근거:** `src/lib/engine.ts` 및 `src/lib/diagnostics.ts` 소스 코드 정밀 분석 완료.
|
||||
- **효과:** 현재 시스템은 고부하 환경에서도 세션을 복구하고 작업을 지속할 수 있는 충분한 수준의 Resilience를 확보하고 있음.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
|
||||
- **Parent:** [[10_Wiki/Projects]]
|
||||
- **Related:** [[Datacollector_MAC]], [[Knowledge_Engine_Architecture]]
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-11 | 실제 코드 분석 기반의 감사 리포트 생성 | CREATE | A |
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
id: autonomous-queue-processing-engine
|
||||
title: Autonomous Queue Processing Engine
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [자율 큐 처리 엔진, 지식 수집 엔진, Knowledge Expansion Engine]
|
||||
source_trust_level: A
|
||||
confidence_score: 0.98
|
||||
created_at: 2026-05-11
|
||||
updated_at: 2026-05-11
|
||||
last_reinforced: 2026-05-11
|
||||
verification_status: applied
|
||||
applied_in:
|
||||
- path: /Volumes/Data/project/Antigravity/Datacollector_MAC/src/lib/engine.ts
|
||||
note: Producer-Consumer 기반 지식 수집 파이프라인 구현
|
||||
- path: /Volumes/Data/project/Antigravity/Datacollector_MAC/src/store/agentStore.ts
|
||||
note: Zustand Persist를 이용한 큐 및 상태 영속화
|
||||
tags: [engine, queue, automation, architecture]
|
||||
---
|
||||
|
||||
# [[Autonomous_Queue_Processing_Engine]]
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
|
||||
> 자율 엔진의 생명력은 단순히 코드가 실행되는 것이 아니라, **상태의 영속성(Persistence)**과 **비동기 파이프라인의 격리**를 통해 프로세스가 중단되어도 마지막 지점에서 즉시 재개할 수 있는 능력에서 나온다.
|
||||
|
||||
## 📖 핵심 개념 (Synthesized Content)
|
||||
|
||||
### 1. Producer-Consumer 모델
|
||||
지식 수집(Research)과 지식 확장(Ontology Expansion)을 분리합니다. 수집된 지식에서 새로운 주제(Links)를 발견하면 큐에 추가(Produce)하고, 엔진은 큐를 순차적으로 소비(Consume)합니다.
|
||||
|
||||
### 2. 상태 영속화 (State Persistence)
|
||||
메모리상의 큐는 휘발성입니다. 엔진의 상태(`queue`, `completed`, `processedCount`)는 반드시 파일 시스템이나 LocalStorage 등에 영속화되어야 하며, `running` 상태에서 비정상 종료 시 재시작할 때 `paused`로 안전하게 복구되어야 합니다.
|
||||
|
||||
### 3. 지능적 틱 조절 (Intelligent Tick Scheduling)
|
||||
하드웨어(예: M4 아키텍처)의 부하를 고려하여 작업 간 간격(Tick)을 동적으로 조절하고, 정체 감지 시 Watchdog 로직이 엔진을 다시 깨울 수 있어야 합니다.
|
||||
|
||||
## 💻 코드 패턴 (Implementation Patterns)
|
||||
|
||||
### 상태 영속화 (Zustand 예시)
|
||||
```typescript
|
||||
persist(
|
||||
(set, get) => ({
|
||||
queue: [],
|
||||
completed: [],
|
||||
// ... actions
|
||||
}),
|
||||
{
|
||||
name: 'engine-storage',
|
||||
partialize: (state) => ({
|
||||
queue: state.queue,
|
||||
completed: state.completed,
|
||||
status: state.status === 'running' ? 'paused' : state.status
|
||||
}),
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Dequeue 및 실행 락
|
||||
```typescript
|
||||
async function processQueue() {
|
||||
if (!isRunning || isConsumerActive || executionLock) return;
|
||||
|
||||
executionLock = true;
|
||||
isConsumerActive = true;
|
||||
|
||||
try {
|
||||
const task = queue[0];
|
||||
await executeTask(task);
|
||||
dequeue();
|
||||
} finally {
|
||||
isConsumerActive = false;
|
||||
executionLock = false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
|
||||
| 항목 | 기준 |
|
||||
|---|---|
|
||||
| 작업 우선순위 | 일반적으로 Depth-First(깊이 우선)를 선호하되, 큐 삽입 시 정렬 필수 |
|
||||
| 중복 처리 | 큐 삽입 전 `completed` 리스트와 현재 `queue` 내 중복을 반드시 체크 |
|
||||
| 종료 조건 | 목표 처리량(Max Count) 또는 모든 작업 완료 시 엔진 정지 |
|
||||
|
||||
## ❌ 안티패턴
|
||||
|
||||
- **In-Memory Only Queue**: 브라우저 리프레시나 프로세스 재시작 시 모든 작업 내역을 잃게 됩니다.
|
||||
- **Concurrent Execution without Lock**: 동일한 큐 아이템에 대해 여러 Consumer가 동시에 달려들어 중복 작업을 수행하거나 상태가 꼬일 수 있습니다.
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **상태:** verified
|
||||
- **출처 신뢰도:** A
|
||||
- **적용 사례:** `Datacollector_MAC`의 `KnowledgeEngine` 클래스에서 검증됨.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
|
||||
- **Parent:** [[Software_Architecture_Patterns]]
|
||||
- **Related:** [[System_Resilience_and_Fault_Tolerance]], [[Data_Schema]]
|
||||
- **Trade-off:** [[Stability vs Flexibility]]
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-11 | Datacollector_MAC 엔진 설계를 바탕으로 최초 생성 | CREATE | A |
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
id: system-resilience-and-fault-tolerance
|
||||
title: System Resilience and Fault Tolerance
|
||||
category: 10_Wiki/Topics
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [결함 허용 시스템, 회복 탄력성 아키텍처, Resilience Patterns]
|
||||
source_trust_level: A
|
||||
confidence_score: 0.95
|
||||
created_at: 2026-05-11
|
||||
updated_at: 2026-05-11
|
||||
last_reinforced: 2026-05-11
|
||||
verification_status: applied
|
||||
applied_in:
|
||||
- path: /Volumes/Data/project/Antigravity/Datacollector_MAC/src/lib/engine.ts
|
||||
note: Exponential Backoff 및 Backend Restart 로직 적용
|
||||
- path: /Volumes/Data/project/Antigravity/Datacollector_MAC/src/lib/diagnostics.ts
|
||||
note: Circuit Breaker 패턴 적용
|
||||
tags: [architecture, reliability, engineering]
|
||||
---
|
||||
|
||||
# [[System Resilience and Fault Tolerance]]
|
||||
|
||||
> [!TIP]
|
||||
> 시스템 회복 탄력성은 단순히 에러가 나지 않는 것이 아니라, **에러가 발생했을 때 어떻게 우아하게 복구(Graceful Recovery)하느냐**의 문제입니다.
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
|
||||
> 분산 시스템과 외부 API 의존도가 높은 현대 소프트웨어에서 안정성은 '완벽한 차단'이 아닌, 지수 백오프(Backoff)와 서킷 브레이커(Circuit Breaker)를 통한 **격리된 실패 제어**와 **자동화된 자가 치유(Self-healing)** 능력에 의해 결정된다.
|
||||
|
||||
## 📖 핵심 개념 (Synthesized Content)
|
||||
|
||||
### 1. 지수 백오프 (Exponential Backoff)
|
||||
실패한 요청을 즉시 재시도하는 대신, 재시도 간격을 지수적으로 늘려나가는 전략입니다. 이는 네트워크 부하를 방지하고 일시적인 장애(Transient Failure)가 해소될 시간을 벌어줍니다.
|
||||
|
||||
### 2. 서킷 브레이커 (Circuit Breaker)
|
||||
외부 서비스 장애가 시스템 전체로 전파되는 것을 막기 위해, 특정 임계값 이상의 실패가 발생하면 요청을 즉시 차단(OPEN)하는 패턴입니다. 일정 시간 후 시범 요청(HALF_OPEN)을 통해 복구 여부를 확인합니다.
|
||||
|
||||
### 3. 격리된 자동 재시작 (Orchestrated Restart)
|
||||
애플리케이션 계층에서 해결되지 않는 하부 서비스(백엔드 브릿지 등)의 장애를 감지했을 때, 격리된 방식으로 해당 서비스를 리셋하고 세션을 복구하는 최후의 복구 수단입니다.
|
||||
|
||||
## 💻 코드 패턴 (Implementation Patterns)
|
||||
|
||||
### Circuit Breaker 상태 관리
|
||||
```typescript
|
||||
let circuit = {
|
||||
status: 'CLOSED', // CLOSED, OPEN, HALF_OPEN
|
||||
failureCount: 0,
|
||||
lastFailureTime: Date.now()
|
||||
};
|
||||
|
||||
function updateCircuit(isSuccess: boolean) {
|
||||
if (isSuccess) {
|
||||
circuit.status = 'CLOSED';
|
||||
circuit.failureCount = 0;
|
||||
} else {
|
||||
circuit.failureCount++;
|
||||
if (circuit.failureCount >= 3) circuit.status = 'OPEN';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 지수 백오프 기반 재시도
|
||||
```typescript
|
||||
const delays = [5000, 15000, 45000]; // 5초, 15초, 45초
|
||||
const retryDelay = delays[consecutiveErrors - 1];
|
||||
setTimeout(() => processNext(), retryDelay);
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준
|
||||
|
||||
| 상황 | 권장 접근법 |
|
||||
|---|---|
|
||||
| 일시적 네트워크 타임아웃 | 3단계 내외의 지수 백오프 재시도 |
|
||||
| 인증 만료 및 세션 오류 | 즉시 자동 복구(Re-auth) 시도 후 실패 시 일시정지 |
|
||||
| 외부 서비스 연속 실패 | 서킷 브레이커 OPEN 하여 리소스 소모 차단 |
|
||||
| 백엔드 프로세스 응답 없음 | 프로세스 격리 재시작(Bridge Restart) 오케스트레이션 |
|
||||
|
||||
## ❌ 안티패턴
|
||||
|
||||
- **무한 재시도 (Infinite Retry Loop)**: 종료 조건 없는 재시도는 서버 리소스를 고갈시키고 로그 폭증을 유발합니다.
|
||||
- **Immediate Retry**: 실패 즉시 재시도하는 것은 'Self-DDOS' 행위이며, 장애 상황을 악화시킵니다.
|
||||
- **이중 카운팅 (Double Counting Errors)**: 서킷 브레이커와 엔진의 백오프 카운터가 독립적으로 소진되어, 실제 재시도 기회를 낭비하는 것을 경계해야 합니다.
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **상태:** verified
|
||||
- **출처 신뢰도:** A (Datacollector_MAC 실구현체 기반)
|
||||
- **적용 사례:** `Datacollector_MAC` 프로젝트의 `engine.ts`와 `diagnostics.ts`에서 검증됨.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
|
||||
- **Parent:** [[Software_Architecture_Patterns]]
|
||||
- **Related:** [[Runtime_Validation]], [[Autonomous_Queue_Processing_Engine]]
|
||||
- **Trade-off:** [[Stability vs Flexibility]]
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-11 | Datacollector_MAC 엔진 리뷰를 기반으로 최초 생성 | CREATE | A |
|
||||
Reference in New Issue
Block a user