Mailflow

클래식 Outlook의 메일을 안정적으로 OpenCode 세션 및 프롬프트에 트리거하고, OpenCode 에이전트에 제어된 메일 MCP 도구 세트를 제공합니다.

Mailflow는 메일 모니터링, 규칙, 세션 호출, 승인 및 UI를 다시 하나의 큰 플러그인에 통합하지 않습니다. 첫 번째 버전은 독립적인 Core, Windows Outlook 커넥터, OpenCode HTTP 어댑터 및 좁은 책임의 MCP를 채택합니다. 기존 win-console은 그대로 유지되며, 호환 도구와 dry-run 우선 마이그레이션 경로를 제공합니다.

최종 형태

flowchart LR
  O["Outlook Classic<br/>Windows 用户会话"] -->|"标准化邮件 / Outlook 命令"| C["Mailflow Core<br/>SQLite · 规则 · 队列 · 审批"]
  C -->|"创建 session + prompt_async"| OC["OpenCode Server"]
  OC --> A["OpenCode 会话 / Agent"]
  A -->|"stdio MCP"| M["Mailflow MCP"]
  M -->|"受 token 保护的 API"| C
  C -->|"草稿 / 导出 / 经审批发送"| O
  UI["本地中文管理台"] --> C
  WC["原 win-console"] -. "兼容工具 / 能力注册 / 可回滚迁移" .-> C

경계는 명확합니다:

• Outlook 커넥터는 Outlook 데이터 어댑테이션, 안정적인 전달 및 Outlook 네이티브 작업만 수행합니다. 구체적인 전송 메커니즘은 Core의 계약이 아닙니다.

• Core는 유일한 진실 공급원으로, SQLite, 규칙 버전, 멱등성, 재시도, 감사, 승인 및 커넥터 명령을 담당합니다.

• Core는 OpenCode HTTP API를 직접 호출하여 세션을 생성하고 프롬프트를 비동기적으로 제출합니다.

• MCP는 세션 내 에이전트에게 메일 읽기, 첨부 파일 내보내기, 답장 초안 작성 및 승인된 전송 도구만 제공합니다. 사서함을 모니터링하지 않습니다.

• 관리 콘솔은 규칙, 실행, 승인 및 장애 복구를 담당하며 Outlook 패널에 의존하지 않습니다.

Outlook 플러그인인가 OpenCode 플러그인인가?

첫 번째 버전은 양쪽 모두 "무거운 플러그인"을 만들지 않습니다. 이는 의도적인 선택입니다:

따라서: 디자인 콘텐츠는 물론 Outlook 확장 패널에 표시될 수 있지만, 핵심을 그 안에 넣어서는 안 됩니다. 클래식 Outlook의 VSTO/COM 추가 기능은 Office 비트 수, 서명, 로드 비활성화 및 프로세스 수명 주기의 영향을 받습니다. 현재 제공 가능한 버전은 독립적인 트레이 방식의 COM 커넥터를 사용합니다. 이후 얇은 VSTO 패널을 추가할 때 Core, MCP 또는 데이터베이스를 변경할 필요가 없습니다. OpenCode 플러그인도 선택적 경험 계층이며, 세션 트리거는 이미 안정적인 HTTP API로 수행됩니다.

v0.1.0에 포함된 내용

• Node.js 24 + 내장 SQLite를 사용하는 제로 런타임 의존성 Core.

• 메일 이벤트 저장, 규칙 매칭, 규칙 버전, run 상태 머신, 멱등 키, 임대, 백오프 재시도 및 데드 레터.

• OpenCode 세션 생성 및 prompt_async, per-message, per-conversation 및 pinned-session 전략 지원.

• 프롬프트 보안 봉투: 메일 내용은 명시적으로 신뢰할 수 없는 데이터로 표시되며, 본문/첨부 파일 상한을 지원합니다.

• 표준 MCP stdio 서버 및 outlook_search, outlook_read, outlook_attachments 등 이전 도구 별칭.

• Windows x64 Outlook Classic 커넥터: 메일 전달, Outlook 네이티브 읽기/쓰기, 명령 멱등성 및 전송 대사.

• send_unknown 안전 폐쇄 루프: 5회 제한 지연 확인, 관리 콘솔 수동 확인, "미전송 확인 후 완전히 새로운 승인 생성"; 어떤 확인도 자동 재전송하지 않습니다.

• 답장 초안은 먼저 Outlook과 동기화한 후 승인을 엽니다. 제목, 수신자 및 본문의 정규화된 해시가 함께 이전 초안 전송을 방지하며, 자동 전송은 기본적으로 비활성화됩니다.

• 한국어 로컬 관리 콘솔, REST API 및 SSE 상태 스트림.

• win-console 규칙/상태 dry-run 가져오기, 기능 등록/하트비트 및 명확한 롤백 경로.

• Linux Core 테스트, Windows 커넥터 빌드 및 태그 기반 GitHub 릴리스 워크플로우.

빠른 시작

1. 다운로드

GitHub Releases에서 다음을 받으세요:

• email-workflow-0.1.0-runtime.zip: Core, MCP, 관리 콘솔, 문서 및 커넥터 소스 코드;

• email-workflow-0.1.0-outlook-classic-win-x64.zip: 자체 포함 Windows x64 커넥터;

• aleygey-email-workflow-0.1.0.tgz: npm 형식 실행 패키지.

Core는 Node.js 24+가 필요합니다. 커넥터는 Windows x64와 클래식 데스크톱 Outlook이 필요합니다.

2. 먼저 키를 초기화하고 OpenCode 보안 구성을 병합하세요

OpenCode를 먼저 시작하지 말고, 기존 opencode.json/opencode.jsonc를 예제 파일로 덮어쓰지 마세요. 런타임 압축 해제 디렉토리에서 .env를 생성하세요:

node dist/src/cli.js init --output .env

examples/opencode-mailflow-complete.json의 agent.mailflow-email 및 mcp.mailflow를 기존 OpenCode 구성에 병합하고, 기존 provider, model, agent, plugin 및 기타 MCP를 유지하세요. 런타임 zip 사용자는 예제의 command를 로컬 절대 경로로 변경하세요. 예:

"command": ["node", "C:\\Mailflow\\email-workflow\\dist\\src\\mcp\\cli.js"]

예제에는 비밀이 포함되지 않습니다. OpenCode를 시작하는 동일한 사용자 환경에 MAILFLOW_MCP_TOKEN이 설정되어야 하며, 값은 .env의 MAILFLOW_API_TOKEN과 동일해야 합니다. 이는 커넥터 토큰이 아닙니다:

$env:MAILFLOW_MCP_TOKEN = "<复制 .env 中 MAILFLOW_API_TOKEN 的值>"

MAILFLOW_CONNECTOR_TOKEN은 Outlook 커넥터만 사용하며, API/MCP 토큰과 달라야 합니다. init은 기본적으로 기존 .env 덮어쓰기를 거부합니다.

3. OpenCode 시작

opencode serve --hostname 127.0.0.1 --port 4096

OpenCode는 방금 MAILFLOW_MCP_TOKEN을 설정한 환경에서 시작해야 예제의 {env:MAILFLOW_MCP_TOKEN}을 해석할 수 있습니다.

4. Mailflow Core 시작

필요에 따라 .env의 OpenCode 주소를 수정한 후, 런타임 압축 해제 디렉토리에서 시작하세요:

node --env-file=.env dist/src/cli.js serve

릴리스 실행은 두 개의 비어 있지 않고 서로 다른 토큰을 구성해야 합니다. 인증되지 않은 Core를 기본 시작 방식으로 지원하지 않습니다. 기본 OPENCODE_MAILFLOW_AGENT=mailflow-email 및 OPENCODE_REQUIRE_SAFE_AGENT=true이며, "일단 실행"을 위해 검증을 끄지 마세요.

http://127.0.0.1:8798에 접속하세요. 관리 콘솔에 처음 들어가면 "설정"에서 API 토큰을 저장하세요.

소스에서 실행:

npm ci
npm run check
npm run dev

5. Outlook 커넥터 시작

Windows 커넥터를 압축 풀고 connector.example.json을 다음으로 복사하세요:

%LOCALAPPDATA%\Mailflow\OutlookConnector\connector.json

Core와 동일한 커넥터 토큰을 설정하고 coreBaseUrl을 http://127.0.0.1:8798로 유지한 후 실행하세요:

.\mailflow-outlook-connector.exe

전체 구성, 키 전달 및 문제 해결 단계는 운영 매뉴얼을 참조하세요.

한 통의 메일이 세션이 되는 방법

1. 커넥터가 안정적인 계약에 따라 메일을 제출합니다. Core는 수신 후 커넥터/이벤트 ID로 중복을 제거합니다. 커넥터의 내부 수집/복구 방식은 비즈니스 계약에 포함되지 않습니다.

2. Core는 메일을 정규화하여 SQLite에 저장하고, 활성화된 규칙의 고정 버전에 대해 매칭을 수행합니다.

3. 일치 시 안정적인 멱등 키로 run을 생성합니다. worker가 run을 임대하고, 오프라인 시 지수 백오프로 재시도합니다.

4. OpenCode 어댑터가 세션을 생성하거나 재사용하고, 프롬프트에 mailflow_run_id 안정 표시를 추가합니다.

5. Core는 프롬프트를 제출하기 전에 대상 mailflow-email 에이전트가 존재하고 여전히 fail-closed 권한인지 확인합니다. 에이전트가 메일 정보가 필요하면 승인된 읽기 전용 MCP 도구를 통해 Core를 콜백합니다.

6. AI 응답은 먼저 Outlook 초안으로 동기화된 후에만 승인이 나타납니다. 승인 시 Core 초안 버전과 Outlook의 제목/수신자/본문 정규화 해시를 동시에 검증합니다. 각 단계는 감사 로그에 기록됩니다.

보안 기본값

• Core는 기본적으로 127.0.0.1만 수신합니다. OpenCode 연결은 루프백 HTTP 또는 HTTPS만 허용합니다. 원격 평문 HTTP는 기본적으로 거부됩니다.

• 첫 번째 시작 시 반드시 node dist/src/cli.js init --output .env를 실행해야 합니다. Core는 API 토큰과 커넥터 토큰이 동시에 존재하고, 서로 다르며, 각각 최소 32 UTF-8 바이트여야 하며, 예제의 공개 플레이스홀더를 거부합니다. MCP는 MAILFLOW_MCP_TOKEN을 통해 API 토큰을 사용하고, 커넥터는 다른 토큰 세트만 사용합니다.

• 본문이 있는 모든 Core 쓰기 요청은 JSON Content-Type을 선언해야 합니다. 비JSON 요청은 즉시 415를 반환합니다.

• 기본 에이전트는 mailflow-email입니다. Core는 프롬프트를 보낼 때마다 OpenCode에서 에이전트 정의를 읽습니다. 먼저 catch-all * deny 경계가 있어야 하며, 그 다음 workspace 내의 read/glob/grep/list만 나열하고, 임의 디렉토리 계층의 *.env/*.env.* deny, 그리고 예제에 정확히 명명된 읽기 전용 Mailflow MCP 도구만 허용해야 합니다. 읽기 전용 MCP 화이트리스트는 search/get/list-attachments/get-run과 순수 읽기 레거시 search/read입니다. 파일을 내보낼 수 있는 outlook_attachments는 포함되지 않습니다. 에이전트가 없거나, 권한 응답을 인식할 수 없거나, 다른 allow가 있으면 fail closed됩니다.

• 규칙은 생성 후 기본적으로 비활성화되며, 먼저 미리보기 후 활성화합니다.

• 메일 본문은 데이터이지 명령이 아닙니다. 첨부 파일은 기본적으로 메타데이터만 노출됩니다.

• 답장은 반드시 사람의 승인이 필요합니다. AI 응답은 먼저 Outlook 초안 동기화를 완료해야 합니다. 승인 인터페이스에서 수정하면 기존 승인이 무효화되고 draft.update가 대기열에 추가되며, 동기화 성공 후 새 승인이 생성되어 사용자가 다시 승인해야 합니다. 승인 후 Outlook에서 제목, To/Cc/Bcc 또는 본문이 변경되면 정규화 해시가 일치하지 않아 전송이 차단됩니다.

• MailItem.Send()의 프로세스 간 결과가 불확실할 때 send_unknown으로 들어갑니다. Core는 5회 제한 지연 상태 확인만 수행합니다. 관리 콘솔에서 "Outlook 확인", "전송 확인" 또는 "미전송 확인"을 할 수 있습니다. 미전송 확인 후 이전 승인은 무효화되고 새 승인이 생성되며, 다시 승인해야 합니다. 시스템은 절대 reconciliation을 자동 재전송으로 바꾸지 않습니다.

• 이전 데이터 가져오기는 기본적으로 dry-run입니다. 적용 가져오기는 명시적 --apply가 필요합니다.

현재 버전의 읽기 전용 에이전트는 선택한 workspace를 계속 읽을 수 있으며, 승인된 MCP 도구를 통해 해당 Core의 다른 메일을 쿼리할 수 있습니다. 이는 run별 독립 데이터 샌드박스가 아닙니다. SQLite는 메일 본문과 원본 스냅샷을 계속 저장하며, v0.1.0에는 자동 보존 기간 정리 작업이 없습니다. 프로덕션 사용 시 전용 최소 권한 workspace/사서함, 제어된 모델 계정, Windows 디렉토리 ACL, 전체 디스크 암호화 및 운영 측 데이터 보존 기간을 구성해야 합니다. 엄격한 프로젝트 간/사서함 간 격리는 추후 per-run capability가 필요합니다. 자세한 내용은 SECURITY.md를 참조하세요.

MAILFLOW_ALLOW_UNAUTHENTICATED_LOOPBACK=1, OPENCODE_ALLOW_INSECURE_REMOTE=1 및 OPENCODE_REQUIRE_SAFE_AGENT=false는 격리된 로컬 개발 진단용이며, 릴리스 구성이 아니며 실제 메일 처리에 사용할 수 없습니다.

Core 또는 OpenCode 서버를 공용 네트워크에 직접 노출하지 마세요. Windows/WSL 간 또는 시스템 간 배포 시 HTTPS, 출처 제한 및 방화벽을 사용하세요. 자세한 내용은 SECURITY.md를 참조하세요.

win-console은 사라지지 않습니다

이전 저장소는 삭제, 덮어쓰기, 기록 변경되지 않습니다. Mailflow는 추가로 다음을 제공합니다:

• 이전 MCP 도구 이름의 호환 별칭;

• external-capabilities 등록 및 하트비트;

• 규칙, 처리된 영수증, 큐 및 체크포인트의 마이그레이션 보고서;

• 기본 dry-run, 명시적 apply, 소스 파일 SHA-256 및 대상 매핑;

• 전환 시 이중 트리거 방지 단계 및 원클릭 논리 롤백.

전체 항목별 매핑은 docs/legacy-win-console-baseline.md를 참조하세요.

문서 탐색

• 전체 설계 문서: 사용자 인터페이스, 6가지 전체 흐름, API, 데이터, 보안, 테스트 및 단계별 구현.

• 아키텍처 경계: Core, 커넥터, 어댑터, MCP 및 선택적 UI로 분할한 이유.

• 운영 매뉴얼: 설치, OpenCode/MCP 구성, 백업, 마이그레이션, 롤백 및 문제 해결.

• win-console 호환 기준: 이전 기능, 이전 데이터 및 롤백 요구 사항.

• v0.1.0 릴리스 노트.

개발 및 검증

npm ci
npm run typecheck
npm test
npm run pack:release

Windows 커넥터:

dotnet build connector/Mailflow.OutlookConnector/Mailflow.OutlookConnector.csproj -c Release

Outlook COM은 실제 Windows 사용자 프로필에 의존하므로, CI는 Windows 컴파일 및 비COM 테스트를 담당합니다. 릴리스 전에 대상 시스템의 클래식 Outlook에서 연결, 메일 수집, 초안 동기화, 2차 승인 및 전송 smoke test를 수행해야 합니다.

라이선스

MIT