@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ko-KR/template-mail.md

@@ -0,0 +1,239 @@
+---
+title: "메일"
+description: "에이전트 기반 이메일 클라이언트입니다. Gmail를 연결하면 상담원이 이메일을 읽고, 초안을 작성하고, 보내고, 정리할 수 있습니다."
+---
+
+# 메일
+
+에이전트 기반 이메일 클라이언트입니다. Gmail 계정을 연결하면 상담원이 이메일을 읽고, 초안을 작성하고, 보내고, 정리할 수 있습니다. 키보드 중심의 빠른 받은편지함도 함께 제공됩니다. 초인적이라고 생각하세요. 하지만 에이전트는 일류 시민이고 코드베이스는 귀하의 소유입니다.
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;min-height:500px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:12px;padding:12px 16px;border-bottom:1.4px solid var(--wf-line)'><strong>Inbox 16</strong><div style='flex:1'></div><span data-icon='search' aria-label='Search'></span><span data-icon='edit' aria-label='Compose'></span><span data-icon='bell' aria-label='Notify'></span></div><div style='display:flex;flex-direction:column;padding:8px 14px;gap:6px'><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><strong>Priya Mehta</strong><span><strong>Q3 launch</strong> — final assets ready for review</span><span>★</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><strong>Acme Billing</strong><span>Your monthly invoice is ready</span><span>11:10 AM</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Marcus Tang</span><span>Onboarding flow research findings</span><span>Yesterday</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>GitHub</span><span>[framework] PR ready for review</span><span>Yesterday</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Linear</span><span>Issue ENG-1287 assigned to you</span><span>May 2</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Stripe</span><span>Weekly payments summary</span><span>Apr 29</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Calendly</span><span>New booking confirmed</span><span>Apr 28</span></div></div></div>"
+}
+```
+
+앱을 열면 키보드 우선 받은 편지함과 스레드 보기가 메일 자체에 계속 집중됩니다. 상담원은 귀하가 현재 어떤 보기에 있고 어떤 스레드를 열어 놓았는지 항상 알고 있으므로 '이것'이 무엇인지 설명하지 않고도 '이것을 보관하세요' 또는 '우호적 거부 초안 작성'이라고 말할 수 있습니다.
+
+```an-diagram title="How a mail request flows" summary="Keyboard shortcuts and agent prompts run the same actions. Email lives in Gmail; drafts, automations, and tracking live in SQL and application_state."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">You drive<br><small class=\"diagram-muted\">J/K/E/R shortcuts</small></div><div class=\"diagram-node\">You ask the agent<br><small class=\"diagram-muted\">\"draft a friendly decline\"</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">list-emails · get-thread · manage-draft · send</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Gmail<br><small class=\"diagram-muted\">multi-account, via OAuth</small></div><div class=\"diagram-box\">SQL + application_state<br><small class=\"diagram-muted\">drafts · automations · tracking</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">Inbox refreshes live</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## 그것으로 무엇을 할 수 있나요
+
+- \*\*키보드 단축키(이동하려면 `J`/`K`, 보관하려면 `E`, 답장하려면 `R`, 작성하려면 `C`)를 사용하여 이메일을 읽고 분류하세요.
+- **여러 개의 Gmail 계정**을 하나의 받은 편지함에서 개인용 및 업무용으로 연결하세요.
+- **상담원에게 할 수 있는 모든 조치를 요청하세요.** "읽지 않은 이메일을 요약해 주세요." "정중하게 거절하는 답장을 작성하세요." "일주일이 지난 모든 Netlify 봇 이메일을 보관하세요."
+- **검토용 대기열 초안.** 팀원 및 Slack 사용자는 에이전트에게 조직 구성원을 위한 이메일을 준비하도록 요청할 수 있습니다. 소유자가 메일에서 검토, 편집 및 전송합니다.
+- **규칙을 사용한 자동 분류.** actions(라벨, 보관, 읽음 표시, 별표, 휴지통)를 사용하여 일반 영어('뉴스레터에서')로 자동화 규칙을 설정하세요.
+- **보내는 이메일의 열기 및 클릭수를 추적**합니다.
+- **한 번의 검색으로 연결된 모든 받은편지함**을 검색하세요.
+- **대량 보관, 내보내기 및 라벨 지정** — 받은편지함 정리에 유용합니다.
+
+## 시작하기
+
+라이브 데모: [mail.agent-native.com](https://mail.agent-native.com).
+
+> **Google에서 경고를 표시할 수 있습니다.** 호스팅된 데모는 Gmail 액세스를 위해 Agent-Native의 공유 Google 앱을 사용하므로 Google에서 계속하기 전에 확인을 요청할 수 있습니다. 자신의 Google OAuth 클라이언트를 사용하려면 로컬에서 실행하세요.
+
+처음 앱을 열 때:
+
+1. 사이드바에서 **설정**을 클릭하세요.
+2. **Google 계정 연결**을 클릭하고 Gmail에 로그인한 후 승인하세요.
+3. (선택사항) 업무용과 개인용으로 두 번째 Google 계정을 연결하세요.
+4. 받은편지함으로 돌아가세요. 실제 Gmail가 동기화됩니다.
+
+Google 계정이 연결되지 않은 경우 앱은 빈 로컬 편지함에 대해 실행됩니다(스크린샷 및 데모에 유용하며 그 외에는 별로 유용하지 않음).
+
+## 에이전트와 대화
+
+에이전트는 매 턴마다 `application_state.navigation`를 읽으므로 사용자가 현재 어떤 보기에 있는지, 어떤 스레드가 열려 있는지, 어떤 메시지에 초점이 맞춰져 있는지 이미 알고 있습니다. 사용자가 이를 알릴 필요가 없습니다. 다음과 같이 말할 수 있습니다:
+
+- "읽지 않은 이메일을 요약해 주세요."
+- "예산에 관한 Alice의 최신 스레드를 찾아보세요."
+- "정중하게 거절하는 답변 초안을 작성하세요."
+- "일주일이 지난 모든 Netlify 봇 이메일을 보관합니다."
+- "별표 표시된 이메일을 열어보세요."
+- "이 초안을 좀 더 공식적으로 만드세요."
+- "그들이 내 이메일을 열었나요?"
+
+텍스트를 선택하고 Cmd+I를 누르면 해당 선택 항목이 다음 메시지와 함께 이동합니다. 따라서 "더 강력하게 만들기"는 강조표시한 내용에 정확하게 적용됩니다.
+
+## 단축키
+
+| 열쇠      | 액션                      |
+| --------- | ------------------------- |
+| `J`       | 다음 이메일               |
+| `K`       | 이전 이메일               |
+| `Up/Down` | J/K와 동일                |
+| `Enter`   | 중요 이메일 열기          |
+| `E`       | 이메일 또는 스레드 보관   |
+| `D`       | 이메일 또는 스레드 휴지통 |
+| `S`       | 별표 표시 또는 별표 해제  |
+| `R`       | 답글                      |
+| `U`       | 읽음/읽지 않음 전환       |
+| `C`       | 새 이메일 작성            |
+| `/`       | 초점 검색창               |
+| `Cmd+K`   | 명령 팔레트 열기          |
+| `G I`     | 받은 편지함으로 이동      |
+| `G S`     | 별표로 이동               |
+| `G T`     | 보낸함으로 이동           |
+| `G D`     | 초안으로 이동             |
+| `G A`     | 보관소로 이동             |
+| `Esc`     | 스레드 닫기 / 검색 지우기 |
+
+## 개발자용
+
+이 문서의 나머지 부분은 메일 템플릿을 포크하거나 확장하는 모든 사람을 위한 것입니다.
+
+### 빠른 시작
+
+메일 템플릿을 사용하여 새 작업 공간 만들기:
+
+```bash
+npx @agent-native/core@latest create my-mail --standalone --template mail
+cd my-mail
+pnpm install
+pnpm dev
+```
+
+또는 기존 에이전트 기반 작업 영역에 메일을 추가합니다.
+
+```bash
+npx @agent-native/core@latest add-app
+```
+
+개발에서 Gmail를 연결하려면 Google OAuth 클라이언트가 필요합니다:
+
+1. [Google Cloud Console](https://console.cloud.google.com/)를 열고 프로젝트를 생성하세요.
+2. APIs & Services → Library에서 **Gmail API**를 활성화합니다.
+3. OAuth 2.0 자격 증명을 만듭니다(유형: 웹 애플리케이션). 승인된 리디렉션 URI로 `http://localhost:8085/_agent-native/google/callback`를 추가하세요.
+4. 실행 중인 앱의 설정 페이지에 클라이언트 ID와 클라이언트 비밀번호를 복사한 후 **Google 계정 연결**을 클릭하세요.
+
+토큰은 `oauth_tokens` SQL 테이블에 저장되며 자동으로 새로 고쳐집니다. 첫 번째 계정이 설정되면 여러 Gmail 계정을 연결할 수 있습니다.
+
+### 주요 기능
+
+**다중 계정 Gmail.** 하나 이상의 Google 계정을 연결한 다음 연결된 받은편지함 전체에 목록, 검색, 초안 작성, 전송, 라벨 지정, 보관처리, 별표 표시 또는 휴지통을 표시합니다.
+
+**초안 워크플로.** 여러 작성 초안은 애플리케이션 상태를 통해 동기화되며 대기열에 있는 SQL 초안을 통해 팀원이나 Slack 사용자는 소유자가 검토하고 보낼 메일을 요청할 수 있습니다.
+
+**자동화 및 추적.** 자연어 분류 규칙은 레이블 지정, 보관, 읽음 표시, 별표 표시, 휴지통 표시 또는 수동 트리거를 수행할 수 있습니다. 보낸 메시지는 열기 및 클릭을 추적할 수 있습니다.
+
+**검색, 대량 actions 및 미리보기.** 공유 actions 파워 받은 편지함 검색, 대량 보관/내보내기 및 상담원이 채팅에 포함할 수 있는 인라인 스레드 미리보기.
+
+### 상담사가 상황을 보는 방법
+
+- **현재 보기 및 스레드** — UI는 탐색할 때마다 `navigation`(보기, threadId, focusEmailId, 검색, 레이블)를 씁니다. 에이전트는 `readAppState("navigation")` 또는 `pnpm action view-screen`를 통해 이를 읽습니다.
+- **초안 열기** — 답장을 작성하는 중 "help me word this"라고 요청하면 에이전트는 일치하는 `compose-{id}` 항목을 읽고 현재 제목과 본문을 확인한 다음 업데이트된 초안을 다시 작성합니다. UI는 편집 내용을 실시간으로 가져옵니다.
+- **스레드 기록** — 컨텍스트 중간 응답의 경우 에이전트는 `pnpm action get-thread --id=<threadId>`를 사용하여 전체 스레드를 가져옵니다.
+
+### 에이전트의 조치 방법
+
+- **메일 작업** — 보관, 휴지통, 별표, 읽음 표시, 보내기, 초안 — 모두 `templates/mail/actions/`에서 `pnpm action <name>` 스크립트로 실행됩니다.
+- **탐색** — 스레드를 열거나 보기를 전환하기 위해 에이전트는 UI가 소비하고 삭제하는 `application_state.navigate`를 작성합니다. `pnpm action navigate` 스크립트가 이를 래핑합니다.
+- **새로 고침** — 변경 후 에이전트는 `pnpm action refresh-list`를 실행하므로 UI가 다시 가져옵니다.
+
+### 데이터 모델
+
+Google 계정이 연결되면 이메일은 Gmail에 저장됩니다. 앱은 상단에 표시됩니다. 연결된 계정이 없으면 이메일은 `getSetting("local-emails")` 아래의 SQL 설정 저장소에 있습니다(기본적으로 비어 있음).
+
+| 매장/테이블                   | 무엇을 담고 있는지                                  |
+| ----------------------------- | --------------------------------------------------- |
+| `getSetting("local-emails")`  | Google 계정이 연결되지 않은 경우 로컬 이메일 대체   |
+| `getSetting("labels")`        | 읽지 않은 개수가 포함된 시스템 및 사용자 라벨       |
+| `getSetting("mail-settings")` | 사용자 프로필, 추적 기본 설정, 서명, 별칭           |
+| `getSetting("aliases")`       | 이메일 별칭                                         |
+| `queued_email_drafts` 테이블  | 팀원이 요청한 초안이 소유자 검토/전송 대기 중       |
+| `email_tracking` 테이블       | 보낸 메시지에 대한 오픈 픽셀 이벤트                 |
+| `email_link_tracking` 테이블  | 보낸 메시지에 대한 링크 클릭 이벤트                 |
+| `application_state` 테이블    | `navigation`, `navigate`, `compose-{id}` 항목(임시) |
+| `oauth_tokens` 테이블         | Google OAuth 토큰(공급자 `"google"`, 계정당 한 행)  |
+
+API를 통해 흐르는 이메일은 `{ id, threadId, from, to, cc, subject, snippet, body, date, isRead, isStarred, isArchived, isTrashed, labelIds, accountEmail, attachments }` 모양을 갖습니다.
+
+```an-schema title="Mail SQL tables" summary="Email itself lives in Gmail. The SQL tables hold what Gmail doesn't: queued drafts, send-tracking events, and OAuth tokens. Settings and ephemeral state live in the settings and application_state stores."
+{
+  "entities": [
+    {
+      "id": "queued_email_drafts",
+      "name": "queued_email_drafts",
+      "note": "Teammate/Slack-requested drafts awaiting owner review",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "assignedTo", "type": "string", "note": "org member who reviews/sends" },
+        { "name": "subject", "type": "string" },
+        { "name": "body", "type": "markdown" },
+        { "name": "status", "type": "enum", "note": "review at /draft-queue/<id>" }
+      ]
+    },
+    {
+      "id": "email_tracking",
+      "name": "email_tracking",
+      "note": "Open-pixel events for sent messages",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "messageId", "type": "string" },
+        { "name": "openedAt", "type": "datetime" }
+      ]
+    },
+    {
+      "id": "email_link_tracking",
+      "name": "email_link_tracking",
+      "note": "Link-click events for sent messages",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "messageId", "type": "string", "fk": "email_tracking.messageId" },
+        { "name": "url", "type": "string" },
+        { "name": "clickedAt", "type": "datetime" }
+      ]
+    },
+    {
+      "id": "oauth_tokens",
+      "name": "oauth_tokens",
+      "note": "Framework table — one row per connected Google account",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "provider", "type": "string", "note": "\"google\"" },
+        { "name": "accountEmail", "type": "string" },
+        { "name": "accessToken", "type": "string" },
+        { "name": "refreshToken", "type": "string" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "email_tracking", "to": "email_link_tracking", "kind": "1-n", "label": "click events" }
+  ]
+}
+```
+
+UI의 경로:
+
+- `/_index.tsx` — 기본 받은 편지함 보기로 리디렉션됩니다.
+- `/$view.tsx` — 목록 보기(`inbox`, `starred`, `sent`, `drafts`, `archive`, `trash` 등).
+- `/$view.$threadId.tsx` — 특정 스레드가 열려 있는 목록 보기.
+- `/email` — 상담원 채팅에 사용되는 내장된 스레드 미리보기.
+- `/settings` — 계정 연결, 추적, 자동화.
+- `/team` — 팀원 및 공유 리소스
+
+### 사용자 정의
+
+메일은 귀하가 변경할 수 있습니다. 중요한 모든 것은 소수의 장소에 있습니다. 그곳에서 시작하세요.
+
+**에이전트 기능 추가.** `defineAction`를 사용하여 `templates/mail/actions/` 아래에 새 파일을 추가합니다. 귀하의 작업은 에이전트 도구, CLI 명령(`pnpm action <name>`) 및 `useActionQuery`/`useActionMutation`를 통해 입력된 프런트엔드 후크 표면이 됩니다. 간단한 예를 보려면 `templates/mail/actions/star-email.ts`를 보거나 여러 개의 하위 actions가 있는 경우에는 `templates/mail/actions/manage-automations.ts`를 살펴보세요. 전체 패턴은 [actions](/docs/actions) 문서를 참조하세요.
+
+**UI 변경.** 경로는 `templates/mail/app/routes/`에 있고 구성 요소는 `templates/mail/app/components/email/` 및 `templates/mail/app/components/layout/`에 있습니다. 이 앱은 `app/components/ui/` 및 Tabler Icons의 shadcn/ui 기본 요소를 사용합니다. 이를 준수하세요.
+
+**에이전트 작동 방식 변경.** 에이전트 안내는 `templates/mail/AGENTS.md` 및 `templates/mail/.agents/skills/`의 skills(`email-drafts`, `real-time-sync`, `security`, `self-modifying-code` 등)에 있습니다. 코드가 아닌 마크다운을 편집하면 상담원 행동이 변경됩니다.
+
+**데이터 또는 설정 변경.** 추적 테이블 및 관련 구조에 대한 스키마는 `templates/mail/server/db/`에 있습니다. 설정 읽기 및 쓰기는 `@agent-native/core/settings`에서 `readSetting` / `writeSetting`를 통해 이루어집니다. 애플리케이션 상태(탐색, 초안, 원샷 명령)는 `@agent-native/core/application-state`의 `readAppState` / `writeAppState`를 사용합니다.
+
+**새로운 자동화 작업 유형 추가.** `templates/mail/actions/manage-automations.ts`에서 작업 스키마를 확장하고 `templates/mail/actions/trigger-automations.ts`에서 실행 프로그램을 확장합니다.
+
+**키보드 단축키 변경.** 키 바인딩 핸들러는 `templates/mail/app/components/email/`에 있습니다. `useHotkeys` 또는 `addEventListener("keydown"`를 검색하여 각 키가 연결된 위치를 찾으세요.
+
+상담원에게 이러한 변경을 요청하세요. 에이전트는 자체 소스를 편집할 수 있습니다. [Self-Modifying Code](/docs/key-concepts#agent-modifies-code)를 참조하세요.