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

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

10_Wiki/Topic_Programming/Pattern_Catalog/Desktop/Background_Worker_Pattern.md

@@ -0,0 +1,68 @@
+---
+id: pattern-background-worker
+title: "Background Worker Pattern"
+category: "Pattern_Desktop"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["background worker", "백그라운드 워커", "worker thread", "job queue", "concurrency limit"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.86
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["pattern", "desktop", "worker", "queue", "concurrency", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/core/queue.ts (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Background Worker Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+Background Worker 는 "무거운/장시간 작업을 메인(UI) 흐름 밖에서, *동시성 상한이 있는 큐* 로 처리" 해 UI 멈춤과 자원 폭주를 동시에 막는 패턴이다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **작업 큐:** 작업을 enqueue, 워커가 꺼내 실행.
+2. **동시성 상한:** 동시에 N개만(CPU/메모리 보호).
+3. **UI 분리:** CPU 바운드는 워커 스레드, I/O 는 비동기.
+4. **결과 반환:** 작업별 Promise/콜백으로 결과 전달.
+5. **백프레셔:** 큐가 넘치면 거부/지연.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **언제 쓰나:** 대량/무거운 작업이 UI 반응성·자원을 위협할 때.
+- **사용 조건:** 작업 단위 분리; 동시성 정책; 결과 전달 경로.
+- **장점:** UI 반응성, 자원 안정(상한), 처리량 제어.
+- **단점:** 복잡도, 결과 동기화, 스레드 통신 비용(CPU 바운드 시).
+- **대안:** 동기 처리(소규모), 외부 잡 시스템(분산), OS 스케줄러.
+- **실패 사례:** 무한 병렬 OOM; 큐 무한 증가(백프레셔 없음); 워커 예외 미처리로 멈춤; UI 스레드에서 무거운 작업.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+class Queue {
+  enqueue(task): Promise = new Promise((res,rej)=>{ this.q.push(()=>task().then(res,rej)); this.next() })
+  next(): if (active < limit && q.length) { active++; run(q.shift()).finally(()=>{active--; next()}) }
+}
+limit = max(2, cpus-1)   # UI 코어 여유
+```
+적용 예: AstraAI 의 ActionQueueManager(동시성 `max(2,cpus-1)`, micro-delay 로 숨통) [S2]. 무거운 LLM 작업은 큐 대신 missionId 락으로 직렬화([[동시성 제어 Lock Queue Transaction]]).
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+동시성은 처리량을 올리지만 자원을 넘으면 역효과 — 상한은 *하드웨어 기준*([[ADR-0004 순차 디스패치 채택]]). 메모리 큰 작업(모델)은 병렬보다 순차가 안전.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI actionQueue + 워처.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Async Concurrency Pattern]], [[Background Task Pattern]], [[AITRAIN 동시성 제어]], [[데스크탑 앱 개발 가이드]]
+- **참조 맥락:** 작은 모델이 무거운 작업을 백그라운드로 뺄 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 워커/잡 큐 지식
+- [S2] AstraAI/src/core/queue.ts — ActionQueueManager
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.

10_Wiki/Topic_Programming/Pattern_Catalog/Desktop/Command_Pattern.md

@@ -0,0 +1,67 @@
+---
+id: pattern-command
+title: "Command Pattern"
+category: "Pattern_Desktop"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["command pattern", "커맨드 패턴", "command registry", "undo redo", "action"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.86
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["pattern", "desktop", "command", "behavioral", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/extension.ts(registerCommand), src/agent/actions/* (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Command Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+Command 패턴은 "요청(동작)을 객체/등록 항목으로 캡슐화" 해 실행을 호출자와 분리하고, 등록·취소(undo)·큐잉·로깅·단축키 매핑을 일관되게 만든다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **명령 캡슐화:** 동작을 id+핸들러로 등록.
+2. **레지스트리:** id→핸들러 매핑(중앙 디스패치).
+3. **undo/redo:** 명령에 역연산 정의(선택).
+4. **메타데이터:** 단축키·메뉴·가시성 조건.
+5. **분리:** UI(버튼/메뉴)는 명령 id 만 알면 됨.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **언제 쓰나:** 여러 진입점(메뉴/단축키/팔레트)이 같은 동작을 부를 때, undo/매크로/큐가 필요할 때.
+- **사용 조건:** 동작을 id 로 표현; 핸들러 등록 메커니즘.
+- **장점:** 호출자-실행자 분리, 재사용, undo/큐/로깅 일관, 확장 용이.
+- **단점:** 명령 폭증, 단순 동작엔 과설계, 상태 전달 설계 필요.
+- **대안:** 직접 함수 호출(소규모), 이벤트(반응형).
+- **실패 사례:** 명령에 무거운 상태 결합; undo 불완전(부분 복원); id 충돌; 등록 해제 누락.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+registry.register('app.save', () => save())     # 명령 = id + 핸들러
+ui.button(onClick = () => exec('app.save'))     # UI 는 id 만
+shortcut('Ctrl+S' -> 'app.save')                # 매핑 일관
+# undo 지원 시: command = { do(), undo() }; history.push(command)
+```
+적용 예: AstraAI 의 `vscode.commands.registerCommand('g1nation.openChat', ...)` (명령 레지스트리)와 action tag 실행기(`<create_file>` 등을 명령처럼 라우팅) [S2]. → [[Tool Calling Pattern]].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+진입점이 하나면 함수 호출이 단순 — 다중 진입점/undo/큐가 필요할 때 Command 가 값을 한다.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI VS Code 명령 등록 + action 실행기.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Event Bus Pattern]], [[Tool Calling Pattern]], [[Plugin Architecture Pattern]], [[데스크탑 앱 개발 가이드]]
+- **참조 맥락:** 작은 모델이 다중 진입점/undo 동작을 설계할 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 Command 패턴(GoF) 지식
+- [S2] AstraAI/src/extension.ts(registerCommand), agent/actions/* — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.

10_Wiki/Topic_Programming/Pattern_Catalog/Desktop/Event_Bus_Pattern.md

@@ -0,0 +1,67 @@
+---
+id: pattern-event-bus
+title: "Event Bus Pattern"
+category: "Pattern_Desktop"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["event bus", "이벤트 버스", "observer", "pub-sub", "EventEmitter", "발행 구독"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.88
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["pattern", "desktop", "event-bus", "pub-sub", "decoupling", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/core/events.ts (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Event Bus Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+Event Bus(발행-구독)는 "발신자와 수신자가 서로를 모른 채 이벤트로 소통" 해 모듈 결합을 낮추는 패턴 — 단, 흐름이 *암묵적* 이 되어 추적이 어려워지므로 이벤트 종류와 계약을 명시해야 한다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **발행/구독:** emit(event) / on(event, handler).
+2. **느슨한 결합:** 발신자는 누가 듣는지 모름.
+3. **이벤트 타입 명시:** enum/상수로 이벤트 카탈로그.
+4. **리스너 수명:** 등록 해제(누수 방지), 최대 리스너 한도.
+5. **동기 vs 비동기:** 핸들러 예외가 발신자에 새지 않게.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **언제 쓰나:** 한 사건에 여러 관심사가 반응(로깅·UI·기록), 모듈을 직접 의존시키고 싶지 않을 때.
+- **사용 조건:** 이벤트 카탈로그 정의; 리스너 수명 관리.
+- **장점:** 결합도↓, 확장 용이(구독 추가), 관심사 분리.
+- **단점:** 흐름 암묵적(추적 난해), 디버깅 어려움, 이벤트 폭발, 순서 보장 약함.
+- **대안:** 직접 호출(흐름 명확, 결합↑), 콜백 주입, 상태 구독(reactive).
+- **실패 사례:** 리스너 해제 누락→누수·중복 실행; 이벤트 이름 오타(문자열); 핸들러 예외가 발신자 중단; "누가 이 이벤트를 듣나" 추적 불가; 이벤트 순환.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+enum E { TASK_STARTED='task:started', ERROR='error:occurred' }   # 카탈로그
+bus.emit(E.TASK_STARTED, payload)         # 발신자: 누가 듣는지 모름
+bus.on(E.TASK_STARTED, h); // ... bus.off(E.TASK_STARTED, h)  # 해제로 누수 방지
+bus.setMaxListeners(20)                    # 폭발 방지
+```
+적용 예: AstraAI 의 `agentEvents`(싱글톤 EventEmitter)와 `AgentEventTypes` enum — 트랜잭션 commit/rollback, task 시작/완료 등을 발행해 모듈 결합을 낮춤 [S2].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+이벤트 버스는 결합을 낮추지만 *흐름을 숨긴다* — 핵심 제어 흐름은 명시 호출이 낫고, 부가/횡단 반응(로깅·기록)에 이벤트가 적합.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI agentEvents(Observer 허브).
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Command Pattern]], [[IPC Pattern]], [[Architecture Separation Pattern]], [[데스크탑 앱 개발 가이드]]
+- **참조 맥락:** 작은 모델이 모듈 간 느슨한 통신을 설계할 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 pub-sub/observer 지식
+- [S2] AstraAI/src/core/events.ts — agentEvents/AgentEventTypes
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.

10_Wiki/Topic_Programming/Pattern_Catalog/Desktop/IPC_Pattern.md

@@ -0,0 +1,69 @@
+---
+id: pattern-ipc
+title: "IPC Pattern"
+category: "Pattern_Desktop"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["IPC", "프로세스 간 통신", "inter-process communication", "message passing", "bridge"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.86
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["pattern", "desktop", "ipc", "messaging", "platform-independent"]
+raw_sources: ["일반 데스크탑 공학 지식", "AstraAI/src/bridge.ts, sidebarProvider.ts (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[IPC Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+IPC 는 "서로 다른 프로세스(메인↔렌더러, 앱↔외부 도구)가 메시지로 소통" 하는 패턴으로, *직렬화 가능한 메시지 계약 + 신뢰 경계 검증* 이 핵심 — 다른 프로세스의 입력은 신뢰되지 않은 입력이다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **메시지 패싱:** 객체 직접 공유 불가 → 직렬화(JSON)해 전달.
+2. **채널/타입:** 메시지에 type 을 두고 핸들러로 라우팅.
+3. **요청-응답 vs 단방향:** 명령은 응답, 알림은 단방향.
+4. **신뢰 경계:** 상대 프로세스 입력을 검증(특히 외부 도구).
+5. **전송 매체:** Electron ipcMain/Renderer, 웹뷰 postMessage, 로컬 HTTP/소켓.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **언제 쓰나:** UI 프로세스↔백그라운드, 앱↔외부 프로그램 통신.
+- **사용 조건:** 직렬화 가능 메시지; 채널 정의; 보안 검증.
+- **장점:** 프로세스 격리(크래시 격리·보안), 언어/도구 무관 연동.
+- **단점:** 직렬화 비용, 객체 공유 불가, 비동기 복잡, 보안 표면.
+- **대안:** 단일 프로세스(스레드/공유 메모리), 파일 교환, 메시지 큐.
+- **실패 사례:** 외부 입력 미검증→임의 명령 실행; 함수/순환 객체 직렬화 실패; 채널 타입 오타; 응답 누락으로 행; 포트 충돌.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+# 웹뷰(렌더러) ↔ 확장(메인): postMessage 프로토콜
+webview.postMessage({ type:'streamChunk', value })       # 확장 → UI
+onMessage(msg): route(msg.type, validate(msg))           # UI → 확장
+
+# 앱 ↔ 외부 도구: 로컬 HTTP 브리지
+http.createServer((req,res) => { body=validate(parse(req)); res.end(handle(body)) })
+```
+적용 예: AstraAI 의 BridgeServer(로컬 HTTP 포트 4825 로 외부 도구↔확장 연결, 서비스 레이어로 로직 분리) + 웹뷰 postMessage 프로토콜([[VSCode 확장 구조와 생명주기]], [[Agent 오케스트레이터 분해]]) [S2].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+프로세스 분리는 격리·보안 이득이 있으나 직렬화·복잡도 비용 — 같은 신뢰 영역의 작은 작업이면 단일 프로세스가 단순. 외부 IPC 는 *항상* 입력 검증.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI BridgeServer + 웹뷰 메시지.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Event Bus Pattern]], [[Tool Calling Pattern]], [[API Client Pattern]], [[데스크탑 앱 개발 가이드]]
+- **참조 맥락:** 작은 모델이 데스크탑(Electron/확장) 프로세스 통신을 설계할 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 IPC 지식(Electron, message passing)
+- [S2] AstraAI/src/bridge.ts, sidebarProvider.ts — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.

10_Wiki/Topic_Programming/Pattern_Catalog/Desktop/Plugin_Architecture_Pattern.md

@@ -0,0 +1,70 @@
+---
+id: pattern-plugin-architecture
+title: "Plugin Architecture Pattern"
+category: "Pattern_Desktop"
+status: "draft"
+verification_status: "applied"
+canonical_id: ""
+aliases: ["plugin architecture", "플러그인 아키텍처", "extension point", "self-registration", "skill loader"]
+duplicate_of: ""
+source_trust_level: "A"
+confidence_score: 0.85
+created_at: 2026-06-13
+updated_at: 2026-06-13
+review_reason: ""
+merge_history: []
+tags: ["pattern", "desktop", "plugin", "extensibility", "platform-independent"]
+raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/skills/externalSkillLoader.ts, src/features/*/handlers.ts (적용 예)"]
+applied_in: ["AstraAI"]
+github_commit: ""
+---
+
+# [[Plugin Architecture Pattern]]
+
+## 🎯 한 줄 통찰 (One-line insight)
+플러그인 아키텍처는 "코어를 안정적으로 두고 기능을 *확장 지점(extension point)* 으로 끼워 넣게" 해 코어 수정 없이 능력을 늘리는 패턴 — 핵심은 *안정된 계약(인터페이스)* 과 *자기 등록* 이다.
+
+## 🧠 핵심 개념 (Core concepts)
+1. **확장 지점:** 코어가 정의한 인터페이스/훅.
+2. **자기 등록:** 플러그인 로드 시 레지스트리에 자기를 등록(side-effect import).
+3. **발견(discovery):** 디렉터리/매니페스트 스캔으로 동적 로드.
+4. **격리/검증:** 플러그인 실패가 코어를 죽이지 않게.
+5. **버전 계약:** 코어 API 버전 호환.
+
+## 📖 세부 내용 (Details · 패턴 명세)
+- **언제 쓰나:** 서드파티/도메인 기능을 코어 변경 없이 추가, 기능 on/off, 생태계 구축.
+- **사용 조건:** 안정된 확장 인터페이스; 로딩/등록 메커니즘; 격리.
+- **장점:** 확장성, 코어 안정, 병렬 개발, 선택적 기능.
+- **단점:** 인터페이스 설계 어려움, 버전 호환 부담, 플러그인 품질/보안 위험.
+- **대안:** 모놀리식(소규모), 설정 플래그, 마이크로서비스.
+- **실패 사례:** 플러그인 예외가 코어 크래시(격리 부재); 안정 안 된 API 로 잦은 호환 깨짐; 등록 순서 의존; 신뢰 안 된 플러그인 권한 과다.
+
+## 💻 코드 패턴 (Code patterns)
+```text
+# 자기 등록 (side-effect import)
+import './features/system/handlers'   # 로드되며 registry.register(...) 실행
+registry.register('cmd:foo', handler)
+
+# 동적 발견
+for file in scan(pluginsDir): plugin = load(file); if validate(plugin): register(plugin)
+try { plugin.run() } catch { /* 격리 — 코어 보호 */ logError() }
+```
+적용 예: AstraAI 의 핸들러 자기등록(`import './features/.../handlers'` 가 slashRouter 에 등록)과 externalSkillLoader(외부 스킬 동적 로드) [S2]. → [[모듈 시스템과 프로젝트 구성]].
+
+## ⚖️ 모순 및 업데이트 (Contradictions & updates)
+플러그인은 유연하나 *안정된 계약* 없이는 버전 지옥. 확장 지점을 최소·신중히 설계하고, 신뢰 안 된 플러그인은 샌드박스/권한 제한.
+
+## 🛠️ 적용 사례 (Applied in summary)
+AstraAI 핸들러 자기등록 + 스킬 로더.
+
+## 🔗 지식 그래프 (Knowledge Graph)
+- **상위/루트:** [[패턴 카탈로그 인덱스]]
+- **관련 개념:** [[Command Pattern]], [[Event Bus Pattern]], [[Architecture Separation Pattern]], [[데스크탑 앱 개발 가이드]]
+- **참조 맥락:** 작은 모델이 확장 가능한 앱(에디터/IDE/툴)을 설계할 때 참조.
+
+## 📚 출처 (Sources)
+- [S1] 일반 플러그인/확장 아키텍처 지식
+- [S2] AstraAI/src/skills/externalSkillLoader.ts, features/*/handlers.ts — 적용 예
+
+## 📝 변경 이력 (Change history)
+- 2026-06-13: 프로젝트 독립 패턴 카드 작성.