bluemsi/connectai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: v2.62.0 - Astra Autonomous Loop (AAL) foundation & enhanced file analysis

Browse Source
This commit is contained in:
g1nation
2026-05-04 12:58:43 +09:00
parent 445d530b63
commit 215c5f9457
23 changed files with 2964 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AgentEngine_Architecture.md
+314
View File
@@ -0,0 +1,314 @@
# AgentEngine Architecture Document
> **Version:** v2.61.0 | **Last Updated:** 2026-05-04 | **Author:** ConnectAI Lab
---
## 1. Overview (설계 개요)
`AgentEngine`은 ConnectAI(Astra) 확장의 핵심 실행 엔진으로, **Producer-Consumer 패턴** 기반의 멀티 에이전트 오케스트레이션을 담당합니다. Planner → Researcher → Writer의 3단계 파이프라인을 통해 사용자의 자연어 요청을 전략 수립, 정보 수집, 최종 보고서 작성이라는 전문화된 단계로 분할 처리합니다.
### 핵심 설계 원칙
| 원칙 | 구현 |
|---|---|
| **의존성 주입 (DI)** | `IAgent` 인터페이스를 통해 에이전트를 런타임에 교체 가능 |
| **명시적 동시성 제어** | `LockManager`(Mutex) + `ActionQueueManager`(Concurrency Limit) |
| **복원력 우선 (Resilience-First)** | `ErrorRecoveryMatrix`를 통한 오류 자동 분류 및 복구 |
| **투명한 상태 관리** | `MissionState`를 통한 감사 이력(Audit Trail) 자동 기록 |
---
## 2. Architecture Diagram (아키텍처 다이어그램)
```
┌──────────────────────────────────────────────────────────────┐
│ AgentWorkflowManager │
│ (Public Entry Point) │
└──────────────────────────┬───────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ AgentEngine │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ 1. LockManager.acquire() ← Mutex (동일 미션 중복 방지) │ │
│ │ 2. ActionQueue.enqueue() ← Concurrency Limit (≤3) │ │
│ │ 3. resilientExecute() ← Error Recovery Matrix │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Planner │──▶│ Researcher │──▶│ Writer │ │
│ │ (IAgent) │ │ (IAgent) │ │ (IAgent) │ │
│ └──────────┘ └──────┬───────┘ └────────────┘ │
│ │ │
│ ┌──────┴───────┐ │
│ │ WriterPrep │ ← Promise.all() 병렬 실행 │
│ │ (Parallel) │ │
│ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MissionState (Audit Trail) │ │
│ │ idle → planner → researcher → writer → completed │ │
│ │ [toStructuredLog()] → JSON 출력 → 모니터링 대시보드 │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
```
---
## 3. Lock Management (락 관리)
### 3.1 LockManager (Mutex)
**파일:** `src/core/lock.ts`
**설계 의도:** 동일한 `missionId`에 대한 중복 실행을 방지합니다. 예를 들어, 사용자가 동일한 질문을 빠르게 두 번 전송한 경우, 두 번째 요청은 첫 번째 요청이 완료될 때까지 대기합니다.
**동작 원리:**
```
Mission A (id: "abc") 시작 → Lock 획득 ✅
Mission B (id: "abc") 시작 → Lock 대기 ⏳ (Mission A 완료까지)
Mission A 완료 → Lock 해제 → Mission B Lock 획득 ✅
```
**핵심 보장:**
- 동일 미션 ID의 순차 실행 보장 (Race Condition 방지)
- `finally` 블록에서 반드시 `release()` 호출 → 데드락 불가
### 3.2 ActionQueueManager (동시성 제어)
**파일:** `src/core/queue.ts`
**설계 의도:** 시스템 전체에서 동시에 실행되는 에이전트 작업 수를 제한하여 리소스 고갈을 방지합니다.
**핵심 파라미터:**
| 파라미터 | 기본값 | 설명 |
|---|---|---|
| `concurrencyLimit` | 3 | 동시 실행 가능한 최대 작업 수 |
| `activeCount` | - | 현재 실행 중인 작업 수 (동적) |
| micro-delay | 10ms | 작업 간 시스템 호흡 시간 |
**Mutex vs Queue의 역할 분리:**
| 구분 | LockManager | ActionQueueManager |
|---|---|---|
| 범위 | 미션 단위 (단일 ID) | 시스템 전체 |
| 목적 | 중복 실행 방지 | 리소스 포화 방지 |
| 방식 | 독점 잠금 (Exclusive) | 동시성 제한 (Bounded) |
---
## 4. Error Recovery Matrix (오류 복구 매트릭스)
### 4.1 오류 분류 체계
`ErrorClassifier`는 에러 객체의 `name`과 `message`를 정규식 패턴 매칭하여 세 범주로 자동 분류합니다.
```
┌──────────────┬──────────┬──────────────┬─────────────────────────────────┐
│ Error Type │ Retries │ Backoff │ Action │
├──────────────┼──────────┼──────────────┼─────────────────────────────────┤
│ TRANSIENT │ 3 │ Exponential │ 자동 재시도 (1s → 2s → 4s) │
│ │ │ (1000ms) │ │
├──────────────┼──────────┼──────────────┼─────────────────────────────────┤
│ PERMANENT │ 0 │ N/A │ 즉시 중단 + 사용자 안내 메시지 │
├──────────────┼──────────┼──────────────┼─────────────────────────────────┤
│ ABORT │ 0 │ N/A │ Graceful Exit (조용한 종료) │
└──────────────┴──────────┴──────────────┴─────────────────────────────────┘
```
### 4.2 분류 패턴 목록
**Transient (재시도 가능):**
- `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `ENOTFOUND`
- `timeout`, `network`, `fetch failed`, `Failed to fetch`
- HTTP `502`, `503`, `429`
- `socket hang up`
**Permanent (즉시 중단):**
- HTTP `401`, `403`, `404`
- `유효한 응답을 받지 못했습니다` (내부 검증 실패)
- `Ollama URL이 설정되지 않았습니다` (설정 누락)
- `invalid model`, `model not found` (모델 문제)
**분류 불가 → Permanent (보수적 처리):**
- 알려지지 않은 오류는 안전하게 Permanent로 분류하여 무한 재시도를 방지
### 4.3 resilientExecute 실행 흐름
```
resilientExecute(agent, ...)
│
├─ attempt 0: agent.execute()
│ ├─ 성공 → return result
│ └─ 실패 → ErrorClassifier.classify(error)
│ ├─ ABORT → throw (즉시 전파)
│ ├─ PERMANENT → throw (사용자 메시지 첨부)
│ └─ TRANSIENT → continue
│
├─ attempt 1: wait 1000ms → agent.execute()
│ └─ (동일 분기)
│
├─ attempt 2: wait 2000ms → agent.execute()
│ └─ (동일 분기)
│
└─ attempt 3: wait 4000ms → agent.execute()
└─ 실패 시 → "재시도 소진" 에러 throw
```
---
## 5. MissionState & Monitoring (상태 관리 및 모니터링)
### 5.1 MissionState 설계 의도
엔진 내부의 상태(`this.stage`)를 독립 객체로 분리하여:
1. **감사 이력(Audit Trail)** 자동 기록: 모든 상태 전환이 타임스탬프, 소요 시간과 함께 기록됨
2. **외부 노출**: `getMissionState()`를 통해 외부 모니터링 시스템이 실시간 상태를 읽을 수 있음
3. **디버깅 지원**: 에러 발생 시 `summarizeAudit()`로 전체 전환 이력을 한 줄로 덤프
### 5.2 toStructuredLog() 출력 포맷
```json
{
"missionId": "mission_1714832400000",
"status": "completed",
"startTime": "2026-05-04T02:40:00.000Z",
"totalElapsedMs": 12450,
"transitionCount": 4,
"transitions": [
{
"from": "idle",
"to": "planner",
"durationMs": 0,
"message": "전략 수립 중...",
"ts": "2026-05-04T02:40:00.000Z"
},
{
"from": "planner",
"to": "researcher",
"durationMs": 3200,
"message": "핵심 정보 수집 및 분석 중...",
"ts": "2026-05-04T02:40:03.200Z"
}
]
}
```
이 포맷은 ELK Stack, Loki, Datadog 등의 외부 시스템에 파싱 없이 직접 인제스트할 수 있습니다.
### 5.3 Mission Control Dashboard
**파일:** `assets/mission_control.html`
`toStructuredLog()`의 JSON 출력을 브라우저에서 시각화하는 독립형 대시보드입니다.
- 에이전트 타임라인 시각화
- 단계별 지연 시간(Latency) 표시
- 미션 상태 및 효율성 분석 지표 제공
---
## 6. IAgent Interface (에이전트 인터페이스)
### 6.1 기본 시그니처
```typescript
interface IAgent {
execute(
input: string,
context?: string,
signal?: AbortSignal,
options?: AgentExecuteOptions
): Promise<string>;
}
```
### 6.2 AgentExecuteOptions (확장 옵션)
| 필드 | 타입 | 용도 |
|---|---|---|
| `context` | `string` | 추가 컨텍스트 |
| `signal` | `AbortSignal` | 중단 시그널 |
| `config` | `Record<string, unknown>` | 에이전트별 커스텀 설정 (temperature, maxTokens 등) |
| `priorResults` | `Record<string, string>` | 이전 단계 중간 결과물 (병렬 파이프라인용) |
**확장 전략:** 새로운 에이전트가 추가될 때 `options.config`에 자유롭게 설정을 넣을 수 있으므로, `IAgent` 시그니처를 변경할 필요가 없습니다.
---
## 7. Test & Benchmark Coverage (테스트 커버리지)
**파일:** `tests/agentEngine.test.ts` | **총 41개 테스트**
| Suite | Tests | Description |
|---|---|---|
| ErrorClassifier | 20 | Transient(10), Permanent(7), Abort(2), Unknown(1) 분류 정확성 |
| Recovery Matrix | 3 | 매트릭스 규칙 정합성 |
| MissionState | 4 | 상태 전환, Audit Trail, JSON 포맷 |
| Engine Integration | 6 | 정상/재시도/즉시중단/취소/재시도소진/상태정리 |
| Performance | 3 | 정상 Latency, 재시도 오버헤드, 즉시 중단 시간 |
| Concurrency & Stress | 4 | 병렬 실행, 혼합 오류, 큐 포화, Race Condition |
### 벤치마크 기준치
| Metric | Measured | Threshold |
|---|---|---|
| Normal Mission Avg Latency | 165ms | < 1,000ms |
| Retry Overhead (2 retries) | 3,012ms | 2,500–10,000ms |
| Permanent Fail Time | 11ms | < 500ms |
| 5 Concurrent Missions | 23ms | < 30,000ms |
| Queue Saturation (10 tasks) | 44ms | all complete |
### 배포 게이트
```json
"vscode:prepublish": "npm run test && npm run compile"
```
모든 41개 테스트가 통과해야만 `.vsix` 패키징이 진행됩니다.
---
## 8. File Map (파일 맵)
```
src/
├── lib/
│ └── engine.ts ← AgentEngine, MissionState, ErrorClassifier,
│ ErrorRecoveryMatrix, IAgent, AgentExecuteOptions
├── core/
│ ├── queue.ts ← ActionQueueManager (Concurrency Limit)
│ └── lock.ts ← LockManager (Mutex)
├── agents/
│ ├── factory.ts ← PlannerAgent, ResearcherAgent, WriterAgent (BaseAgent)
│ └── AgentWorkflowManager.ts ← Public API (runStrictWorkflow)
└── utils.ts ← logInfo, logError, logWarn (→ VS Code Output Channel "Astra")
tests/
└── agentEngine.test.ts ← 41 integration tests + benchmarks
assets/
└── mission_control.html ← Mission Control Dashboard (standalone)
```
---
## 9. Maintenance Notes (유지보수 참고)
### 새 에이전트 추가 시
1. `IAgent`를 구현하는 새 클래스를 `factory.ts`에 추가
2. `AgentEngine` 생성자에 주입 (DI)
3. `PipelineStage` 타입에 새 단계 추가
4. `AgentWorkflowManager.mapStageToUI()`에 UI 매핑 추가
### 새 오류 패턴 추가 시
1. `ErrorClassifier.TRANSIENT_PATTERNS` 또는 `PERMANENT_PATTERNS`에 정규식 추가
2. `tests/agentEngine.test.ts`의 해당 describe 블록에 테스트 케이스 추가
3. `npm run test:engine`으로 검증
### 동시성 제한 변경 시
`src/core/queue.ts`의 `new ActionQueueManager(N)` 생성자 인자를 조정합니다.
기본값은 3이며, 리소스 여유에 따라 조정 가능합니다.
docs/records/ConnectAI/bugs/BUG-0001-volumes-data-project-antigravity-connectai-프로젝트-코드-리뷰-해줄-수-있.md
+16
View File
@@ -0,0 +1,16 @@
# Bug: /Volumes/Data/project/Antigravity/ConnectAI 프로젝트 코드 리뷰 해줄 수 있어? 개선할 부분이 있는지, 그러고...
## Date
2026-05-04
## Symptom
/Volumes/Data/project/Antigravity/ConnectAI 프로젝트 코드 리뷰 해줄 수 있어? 개선할 부분이 있는지, 그러고 잘된점과 문제점들이 있는지. 없으면 없다고 말해도되.
## Cause
Captured automatically from the current conversation. Confirm root cause during follow-up review if needed.
## Fix
## 간단 요약 이 요청은 프로젝트 지식 생성이 아니라 코드리뷰와 제품 평가 요청입니다. 확인된 파일 구조 기준으로 보면, 이 프로젝트는 지식 수집 워크플로우를 앱 형태로 묶어 운영하려는 도구로 보이며, 먼저 데이터 수집 흐름의 안정성, 외부 연동 실패 처리, 수집 결과의 저장/재처리 가능성을 중심으로 평가해야 합니다. ## 확인된 근거 대상 경로: `/Volumes/Data/project/Antigravity/ConnectAI` 확인된 우선 파일: - `package.json` - `docs/records/ConnectAI/README.md` - `README.md` - `docs/Advanced_Features_Implementation_Guide.md` - `docs/AgentEngine_Architecture.md` - `docs/records/ConnectAI/chronicle.config.json` - `docs/records/ConnectAI/decisions/ADR-0...
## Prevention
Keep automatic records tied to the active project and verify the relevant test or reproduction path.
docs/records/ConnectAI/chronicle.config.json
+11
View File
@@ -0,0 +1,11 @@
{
"projectId": "connectai",
"projectName": "ConnectAI",
"projectRoot": "/Volumes/Data/project/Antigravity/ConnectAI",
"recordRoot": "/Volumes/Data/project/Antigravity/ConnectAI/docs/records/ConnectAI",
"description": "Auto-detected from the local project path in the conversation.",
"corePurpose": "Capture project direction, architecture discussion, decisions, and development notes as Markdown.",
"detailLevel": "standard",
"createdAt": "2026-05-04T03:27:46.314Z",
"updatedAt": "2026-05-04T03:27:46.316Z"
}
docs/records/ConnectAI/decisions/ADR-0001-volumes-data-project-antigravity-connectai-이-프로젝트를-지금-개발-중에-.md
+19
View File
@@ -0,0 +1,19 @@
# ADR: /Volumes/Data/project/Antigravity/ConnectAI 이 프로젝트를 지금 개발 중에 있어. 코드 리뷰를 하고 잘된점과 ...
## Status
accepted
## Context
/Volumes/Data/project/Antigravity/ConnectAI 이 프로젝트를 지금 개발 중에 있어. 코드 리뷰를 하고 잘된점과 부족한 부분, 앞으로 개선해야할게 있다면 뭔지 알려주면 좋겠어.
## Decision
## 간단 요약 이 요청은 프로젝트 지식 생성이 아니라 코드리뷰와 제품 평가 요청입니다. 확인된 파일 구조 기준으로 보면, 이 프로젝트는 지식 수집 워크플로우를 앱 형태로 묶어 운영하려는 도구로 보이며, 먼저 데이터 수집 흐름의 안정성, 외부 연동 실패 처리, 수집 결과의 저장/재처리 가능성을 중심으로 평가해야 합니다. ## 확인된 근거 대상 경로: `/Volumes/Data/project/Antigravity/ConnectAI` 확인된 우선 파일: - `package.json` - `docs/records/ConnectAI/README.md` - `README.md` - `src/agent.ts` - `src/agents/AgentWorkflowManager.ts` - `src/agents/factory.ts` - `src/bridge.ts` - `src/config.ts` - `src/extension.ts` - `src/MrBeast_Premium_10.md` 확인된 구조 일부...
## Reason
Captured automatically because the conversation contained decision-oriented language.
## Alternatives
Not captured yet.
## Consequences
- Future prompts should treat this as project context unless the user changes direction.
docs/records/ConnectAI/timeline.md
+6
View File
@@ -21,3 +21,9 @@
- Tuned Second Brain retrieval by query intent so UX/business/approval questions prioritize customer journey, requirement fit, and business value notes over generic architecture notes.
- Tuned answer readability: paragraph-first summaries, fewer bullet-heavy sections, clearer numbered-section spacing, and larger markdown headings in the sidebar.
- Added local project path preflight for code review requests so the agent scans accessible Antigravity project folders before asking for uploads.
## 2026-05-04
- Auto decision record created: decisions/ADR-0001-volumes-data-project-antigravity-connectai-이-프로젝트를-지금-개발-중에-.md
## 2026-05-04
- Auto bug record created: bugs/BUG-0001-volumes-data-project-antigravity-connectai-프로젝트-코드-리뷰-해줄-수-있.md