MindAgency/mind-agency

Mind Agency는 로컬 우선(local-first)의 다중 에이전트 협업 플랫폼입니다. 이를 통해 전문화된 AI 에이전트를 생성하고, 이들을 그룹으로 구성하며, 작업을 할당하고, 워크플로우를 실행하고, 결과를 검토하며, 발생한 모든 과정을 감사 가능한 기록으로 보관할 수 있습니다.

이 프로젝트는 Next.js 인터페이스, 임베디드 WebSocket 이벤트 계층, 워크플로우 엔진, MCP 도구, 영속적인 로컬 데이터, 그리고 Electron을 통한 데스크톱 패키징을 결합합니다.

이번 브랜치는 현재의 테스트/런타임 회귀(regression)를 수정하고 GitHub에서 리포지토리 문서를 더 쉽게 읽을 수 있도록 만드는 데 중점을 둡니다.

통합 테스트는 방출된 이벤트가 IPCStore를 통해 가시적일 것으로 예상했지만, 현재의 EventBus.emit() 경로는 이벤트를 감사 아웃박스(audit outbox)에만 영속적으로 저장했습니다. 그 결과, 유효한 이벤트가 방출된 후에도 events:last, events:recent, 그리고 events:count와 같은 키들이 누락될 수 있었습니다.

수정 사항은 src/lib/event-bus.ts 내부에 IPC 동기화(synchronization)를 추가합니다:

• events:last는 가장 최근에 방출된 이벤트를 저장합니다.
• events:recent는 마지막 100개의 방출된 이벤트를 저장합니다.
• events:count는 승인된 이벤트가 발생할 때마다 증가합니다. - IPC 쓰기 실패는 포착되어 로깅되므로 이벤트 전송이 충돌하지 않습니다.

이를 통해 인-프로세스(in-process) 이벤트 전달, 아웃박스 영속성, 그리고 크로스-프로세스(cross-process) IPC 상태가 일치하게 유지됩니다.

IPCStore.set()은 값을 JSON으로 저장하므로, 10과 같은 숫자는 JSON 문자열 '10'으로 저장됩니다. 이전의 increment() 구현은 원시 데이터베이스 값(raw database value)을 parseInt()로 직접 파싱했기 때문에, 유효하지 않거나 이전에 오염된 값에 취약했습니다.

업데이트된 src/lib/ipc.ts 구현:

• 기존 값을 JSON.parse()를 통해 읽습니다.;
• 유한 숫자 값(finite numeric values)만 허용합니다.;
• 필요할 때 레거시 원시 숫자 파싱으로 폴백(fallback)합니다.;
• NaN을 생성하는 대신, 유효하지 않은 카운터 값은 0으로 재설정됩니다.

이는 events:count와 같은 카운터가 손상되는 것을 방지합니다.

agent-identity와 agent-proxy는 MCP 구성을 빌드할 때 src/lib/data-dir.ts에서 getApiBase()와 getWsBase()를 호출하도록 변경되었습니다. 테스트에서는 data-dir을 모킹(mocked)했습니다.

하지만 이러한 최신 내보내기(exports)는 포함하지 않아 설정이 검증되기 전에 Vitest가 실패하게 만들었습니다.

테스트 목업은 다음에서 업데이트되었습니다:

tests/agent-identity.test.ts

tests/agent-proxy.test.ts

이제 안정적인 로컬 테스트 URL을 제공합니다:

이전 README에는 여러 섹션에 mojibake/인코딩 아티팩트가 포함되어 있었습니다. 이 파일은 다음 내용으로 깨끗하고 읽기 쉬운 영어 README로 재작성되었습니다:

• 프로젝트 개요(project overview);
• 기능 요약(feature summary);
• 빠른 시작 명령어(quick-start commands);
• 환경 설정(environment configuration);
• 일반 개발 명령어(common development commands);
• 아키텍처 노트(architecture notes);
• 로컬 검증 상태(local verification status);
• 이 상세한 브랜치 변경 요약(detailed branch-change summary).

• Node.js 18 이상
• npm
• Windows가 주요 패키징 대상

git clone https://github.com/MindAgency/mind-agency.git
cd mind-agency
npm install
...

http://localhost:3000을 엽니다.

.

npm run dev:ws

npm run dev:all

API 키 및 제공자 프로필은 앱 설정 페이지에서 구성할 수 있습니다.

런타임 데이터는 src/lib/data-dir.ts를 통해 해결됩니다.

:

| 변수 | 목적 | 기본값 |
|---|---|
MIND_DATA_DIR | 에이전트, 그룹, 감사 로그(audit logs), IPC 및 메모리를 위한 쓰기 가능 데이터 디렉토리 | 프로젝트 루트 |
MIND_APP_DIR | 번들링된 앱 코드를 위한 읽기 전용 애플리케이션 디렉토리 | MIND_DATA_DIR |
PORT | Next.js API/UI 포트 | 3000 |
WS_PORT | WebSocket 서버 포트 | 3001 |
HOSTNAME | 서버 측 설정에 사용되는 API 호스트 | 127.0.0.1 |

npm run build # MCP 서버 및 프로덕션 Next.js 앱 빌드
npm test # Vitest 테스트 스위트 실행
npm run build:mcp # MCP 그룹 서버 번들링
...

Windows PowerShell에서 실행 정책이 npm을 차단하는 경우, 대신 npm.cmd를 사용하십시오:

npm.cmd test
npm.cmd run build

mind-agency/
|-- src/
| |-- app/ Next.js 라우트 및 API 엔드포인트
...

런타임 시, 핵심 구성 요소들은 다음과 같이 함께 작동합니다:

Next.js UI/API
|
v
...

저장소에는 에이전트(agents), 세션(sessions), 워크플로우(workflows), 이벤트 버스 동작(event bus behavior), IPC, 프로바이더(providers), 스킬(skills), 그룹(groups) 및 API 연동 유틸리티에 대한 단위 테스트와 통합 커버리지가 포함되어 있습니다.

최신 로컬 검증:

Test Files 51 passed
Tests 211 passed

Copyright 2026 Toufumind