Work Assistant

이메일이 사람이나 지능형 에이전트가 사용할 수 있는 로컬 아카이브가 됩니다.

프로바이더에 종속되지 않음 · 여러 사서함 · CLI · MCP · 인간 검토

데모 사용해보기 · 에이전트에 연결하기 · 보안 이해하기 · 프로젝트 상태

Work Assistant란 무엇인가요?

Work Assistant는 지능형 도구로 이메일을 정리하고 사용하기 위한 로컬 시스템입니다.

이 시스템은 하나 이상의 사서함에서 메시지를 수집하고, 이를 정규화하여 로컬 SQLite 아카이브에 보관합니다. 이 아카이브를 바탕으로 연락처와 상호작용 보기를 재구성합니다. 사람은 명령줄에서 이 시스템을 사용할 수 있습니다. Codex나 Claude와 같은 에이전트는 MCP 프로토콜을 통해 사용할 수 있습니다.

Work Assistant는 전통적인 메일 클라이언트도, 단순한 스킬도 아닙니다:

• core는 계정, 아카이브, 검사, 제안된 콘텐츠를 관리합니다;

• CLI는 모델 없이 사람이 core를 사용할 수 있게 합니다;

• MCP 서버는 에이전트에게 구조화된 도구를 제공합니다;

• skill은 에이전트가 허용된 범위 안에서 이러한 도구를 사용하는 방법을 가르칩니다;

• adapter는 특정 이메일 서버스를 core에 연결합니다.

공개 core는 이메일을 보내지 않습니다. 준비된 응답은 별도의 승인된 작업이 실행되기 전까지 로컬 후보로 남습니다.

Related MCP server: Mailing Manager MCP

왜 존재하는가

사용자 사서함에는 메시지 개별만 있는 것이 아닙니다. 대화, 사람, 첨부 파일, 결정, 아직 열려 있는 작업 등이 들어 있습니다. 일반적인 클라이언트는 현재 메일을 잘 보여 주지만, 이 역사를 작업 지식으로 재사용하기는 어렵게 만듭니다.

Work Assistant는 세 가지 수준을 분리합니다:

1. 로컬 아카이브: 수집된 내용의 보존하고 그 무결성을 검사합니다.

2. 지식 보기: 아카이브에서 연락처와 상호 작용을 재구성합니다. 파생된 것이며 다시 생성할 수 있습니다.

3. 에이전트 표면: 모델이 통제된 작업을 통해 검색, 읽기, 콘텐츠 준비를 할 수 있습니다.

지식 보기는 원본 소스가 아니며, 그 자체로 검증된 백업을 만들지 못합니다. 진짜 백업이려면 복사, 보존, 검사, 복구 시험이 필요합니다.

작동 원리

flowchart LR
  Persona[Persona] --> Agente[Agente intelligente]
  Agente -->|strumenti MCP| Gateway[Gateway MCP]
  Gateway -->|IPC locale autenticato| Broker[Broker locale]
  Broker --> Archivio[(Archivio locale)]
  Broker --> Vista[Vista di conoscenza]
  Broker --> Candidati[Candidati di risposta]
  Adapter[Adapter del provider] --> Broker

  classDef paper fill:#f7f2e7,stroke:#294b37,color:#172019;
  classDef sage fill:#dce8d8,stroke:#294b37,color:#172019;
  classDef accent fill:#aa593e,stroke:#aa593e,color:#f7f2e7;
  class Persona,Archivio,Vista,Candidati paper;
  class Gateway,Broker,Adapter sage;
  class Agente accent;

브로커가 신뢰 경계입니다. 평문 데이터를 읽고, 응용 규칙에 따라 가명화를 적용한 뒤, 게이트웨이에게 선언된 스키마만 돌려줍니다. 프로바이더의 식별자는 불투명한 참조가 됩니다. 인식할 수 없는 메타데이터는 경계를 가스지 않습니다.

데모 체험하기

이 데모는 합성 신원과 문의만 사용합니다. 자격 증명이나 실제 사취 않이 없어도 됩니다.

요구 사항

• Python 3.11 이상;

• Git;

• macOS, Linux 또는 Windows.

1. 프로젝트 설치

git clone https://github.com/Wulfgardr/work-assistant.git
cd work-assistant
python3 -m venv .venv

macOS 또는 Linux에서 가상 환경을 활성화합니다:

source .venv/bin/activate

Windows PowerShell에서는:

.venv\Scripts\Activate.ps1

Work Assistant를 설치합니다:

python -m pip install .

2. 설정 생성

work-assistant --config work-assistant.toml init

이 명령은 운영 체제별 데이터 폴더를 만들어 줍니다. 이 아카이브, 키, 신원 등기는 repository에 보관되지 않습니다.

3. 합성 사서함 로드

work-assistant --config work-assistant.toml sync --account personal
work-assistant --config work-assistant.toml sync --account team
work-assistant --config work-assistant.toml list
work-assistant --config work-assistant.toml knowledge
work-assistant --config work-assistant.toml verify

verify 명령은 SQLite 잘 무결성과 메시지 해시를 검사합니다. 이는 백업을 복원할 수 있다는 것을 증명하지 않습니다.

에이전트와 Work Assistant 사용하기

Codex, Claude 등의 다른 MCP 클라이언트는 동일한 표면을 사용합니다. 모델은 CLI 안에 빌트인이 아닙니다.

MCP 지원 설치:

python -m pip install '.[mcp]'

1. 로컬 브로커 실행

신뢰할 수 있는 로컬 터미널에서 실행합니다:

work-assistant --config work-assistant.toml broker

브로커는 실행 상태를 유지되어야 합니다. 없는 경우, MCP 게이트웨이는 중지되며 아카이브에서 직접 읽지 않습니다.

두 번째 터미널에서 필요한 두 경로를 가져옵니다:

work-assistant --config work-assistant.toml broker-info

2. Codex에 서버 등록

broker-info 출력의 값들로 두 플레이스홀더를 교체합니다:

codex mcp add work-assistant -- \
  "$PWD/.venv/bin/work-assistant" \
  mcp \
  --broker-address '<BROKER_ADDRESS>' \
  --broker-auth-file '<BROKER_AUTH_FILE>'

Windows에서는 .venv\Scripts\work-assistant.exe를 사용합니다.

요청 예:

Work Assistant를 사용하세요. 비밀성 모드를 확인하고, personal 사함함을 동기화하고, 최근 메시지를 보여 주고, 응답 후보를 붐미도록 합니다. 아무것도 보내지 마세요.

선택적 skill은 skills/work-assistant에 있습니다. 스킬은 다른 절차를 추가하지만 MCP 서버를 대체하지는 않습니다.

3. Claude Code에 서버 등록

claude mcp add work-assistant -- \
  "$PWD/.venv/bin/work-assistant" \
  mcp \
  --broker-address '<BROKER_ADDRESS>' \
  --broker-auth-file '<BROKER_AUTH_FILE>'

Claude Desktop에서는 동일한 stdio 서버를 구성합니다:

{
  "mcpServers": {
    "work-assistant": {
      "command": "/percorso/assoluto/work-assistant/.venv/bin/work-assistant",
      "args": [
        "mcp",
        "--broker-address",
        "<BROKER_ADDRESS>",
        "--broker-auth-file",
        "<BROKER_AUTH_FILE>"
      ]
    }
  }
}

에이전트 없이 CLI 사용

CLI는 결정적입니다. 자연어 요청을 해석하지 않습니다.

work-assistant --config work-assistant.toml list --account personal --limit 10
work-assistant --config work-assistant.toml show --account personal --id p-001

로컬 응답 후보를 저장하려면:

printf 'Grazie. Verifico il documento entro venerdì.\n' > risposta.txt
work-assistant --config work-assistant.toml draft-candidate \
  --account personal \
  --to sam@example.test \
  --subject 'Re: Revisione del progetto' \
  --in-reply-to p-001 \
  --body-file risposta.txt

응답에는 sent: false가 포함됩니다. 어떤 것도 프로바이더에 쓰지 않습니다.

터미널에 접근하는 에이전트는 MCP를 사용해야 합니다. SQLite를 직접 읽거나 CLI의 평문 출력을 직접 읽지 마세요.

여러 사서함 구성

[accounts] 아래의 각 표는 독립 표시합니다.

schema_version = 1
data_dir = "/percorso/esterno/al/repository"

[privacy]
mode = "all"
default_action = "pseudonymize"

[accounts.personal]
provider = "demo"
source = "./examples/demo-mailbox.jsonl"
address = "alex@example.test"

[accounts.team]
provider = "demo"
source = "./examples/team-mailbox.jsonl"
address = "team@example.test"

이 저장소에는 데모용 어댑터만 포함됩니다. 실제 어댑터는 docs/PROVIDER_ADAPTERS.md에 설명된 계약을 구현해야 합니다.

Zimbra와 Carbonio

공개 버전에는 HAR 파일에서 Zimbra 또는 Carbonio 세션을 준비하는 로컬 온보딩이 포함됩니다. 실제 동작하는 Zimbra 어댑터는 포함되지 않습니다.

sequenceDiagram
  participant A as Agente
  participant P as Persona
  participant B as Browser
  participant C as CLI locale
  A->>P: Spiega i passaggi e controlla lo stato
  P->>B: Esegue login e autenticazione a due fattori
  P->>C: Importa localmente il file HAR
  C-->>P: Conferma solo nomi dei cookie e stato
  Note over A,C: Password, OTP, HAR e valori dei cookie non entrano nel modello

로컬 명령은 다음과 같습니다:

work-assistant --config work-assistant.toml import-zimbra-har \
  --account work \
  --har /percorso/locale/session.har

이 명령은 HAR 파일을 삭제하지 않습니다. 검증 완료 후, 민감 콘텐츠에 맞게 내보내기를 옮기거나 삭제해야 합니다.

데이터 보호 방법

Work Assistant는 세 가지 모드를 제공합니다:

선택 규칙 예:

[privacy]
mode = "selective"
default_action = "pseudonymize"

[[privacy.sender_rules]]
pattern = "newsletter@example.test"
action = "allow_raw"

[[privacy.sender_rules]]
pattern = "*@sensitive.example"
action = "pseudonymize"

에이전트 응답에는 규칙의 불투명한 식별자만 포함되고, 말 그대로 값 자체는 포함되지 않습니다.

선택적 신원 등록은 기본적으로 <data_dir>/privacy/entities.json에 있습니다. POSIX 시스템에서는 사용자가 소유권으로, 권한은 0600이어야 합니다.

가명화는 취소 가능하며, 익명성을 보장하지 않습니다. 희귀한 사실, 문맥, 글쓰기 스타일 또는 인식되지 않은 용어로 사람을 식별할 수 있습니다.

브로커가 실제 신뢰 경계가 되려면 데잇터 폴더가 에이전트가 읽을 수 있는 모든 작업 공간 외부에 있어야 합니다. 브로커는 통제된 데모를 위한 명시적이지만 안전하지 않은 override가 아니면 이를 구성에서 거부합니다.

실제 메시지를 사용하기 전에 SECURITY.md를 읽으십시오.

라이트브레이크 보안 검토

2026년 8월 24일, Daybreak 검토가 브로커, 가명화, IPC 및 MCP 표면을 분석했습니다. 그 목록에서 중간 심각도 1건, 낮은 심각도 6건의 총 0건의 문제를 발견했습니다.

0.3.0 버전이 다음을 수정합니다:

• 데이터와 키가 기본적으로 리포지토리 외부에 위치

• 보호된 저장소가 에이전트 작업 공간 안에 있으면 브로커가 거부;

• 외부 신원 등록과 권한 검사;

• MCP 스키마를 닫힌 목록으로, 공급되지 않은 메타데이터 제외;

• 선택 규칙에 대해 불투명한 식별자;

• 고정된 워커 수와 유휴 연결 시간 제한;

• 연결, 인증, 요청, 응답 전체에 포괄적 타임아웃.

보고서, 근거, 잔여 제한사항은 docs/security/DAYBREAK-REVIEW.md에 있습니다.

백업과 복구

Work Assistant은 정규화된 메시지와 관련 해시를 보관합니다. 이는 아카이브를 점검 가능하게 하지만, 자동으로 복원 탄력적인 백업으로 만들어 주지는 않습니다.

검증된 백업을 충족하려면 다음을 정의하고 입증해야 합니다:

• 포함할 메시지 및 첨부;

• 암호화와 키 관리;

• 백업 빈도, 보관 기간, 버전;

• 해시 검증;

• 격리 환경에서의 복구 절차;

• 기대 콘텐츠와 복원 콘텐츠 비교.

verify 함수는 현재 archive를 검사합니다. 절대 복구를 수행하지 않습니다.

프로젝트 상태

Work Assistant는 alpha 프로젝트입니다.

구현된 기능:

• 프로바이더에 독립적인 core;

• 여러 사서하게;

• 데모용 추가 어댑터;

• 해시가 있는 SQLite 크기;

• 로컬 보관된 연락처와 상호작용 통합 보기;

• CLI;

• MCP 게이트웨이와 로컬 브로커;

• 가역 가명 처리;

• agent용 스킬;

• Zimbra 및 Carbonio 준비용 온보딩.

구현되지 않은 항목:

• 실제 프로바이더용 프로덕션 어댑터;

• 이메일 전송;

• 전체 백업 및 복구 증명;

• 첨부 파일의 바이너리 콘텐츠 가명화;

• 익명성 보장.

개발 및 기여

python -m pip install '.[dev,mcp]'
pytest
python scripts/privacy_check.py
work-assistant benchmark-privacy --iterations 50

코드, 테스트, 스크린샷, issue 및 pull request에는 표시된 가상 데이터만 사용해야 합니다. 프로젝트 규칙은 CONTRIBUTING.md에서 읽어 보십시오.

라이선스

Work Assistant는 MIT 라이선스로 배포됩니다.