@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/zh-CN/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 可能会显示警告：** 托管演示使用 Agent-Native 的共享 Google 应用程序进行 Gmail 访问，因此 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 凭证（类型：Web 应用程序）。添加 `http://localhost:8085/_agent-native/google/callback` 作为授权重定向 URI。
+4. 将客户端 ID 和客户端密钥复制到正在运行的应用的“设置”页面，然后点击“**连接 Google 帐户**”。
+
+令牌存储在`oauth_tokens` SQL表中并自动刷新。一旦第一个帐户设置完毕，您就可以连接多个 Gmail 帐户。
+
+### 主要功能
+
+**多帐户 Gmail。** 连接一个或多个 Google 帐户，然后在连接的收件箱中列出、搜索、草稿、发送、标记、存档、加星标或回收站。
+
+**草稿工作流程。** 多个撰写草稿通过应用程序状态同步，排队的 SQL 草稿让队友或 Slack 用户请求邮件供所有者审阅和发送。
+
+**自动化和跟踪。**自然语言分类规则可以手动标记、存档、标记已读、加星标、垃圾箱或触发；发送的消息可以跟踪打开和点击。
+
+**搜索、批量 actions 和预览。**共享 actions 强大的收件箱搜索、批量存档/导出以及代理可以嵌入聊天中的内联线程预览。
+
+### 代理如何查看您的上下文
+
+- **当前视图和线程** — 每当您导航时，UI 都会写入 `navigation`（视图、threadId、focusedEmailId、搜索、标签）。代理通过 `readAppState("navigation")` 或 `pnpm action view-screen` 读取它。
+- **打开草稿** — 如果您正在撰写回复并询问“帮我写一下这个”，代理会读取匹配的 `compose-{id}` 条目以查看您当前的主题和正文，然后写回更新的草稿。 UI 实时进行编辑。
+- **线程历史记录** - 对于上下文中间回复，代理使用 `pnpm action get-thread --id=<threadId>` 获取完整线程。
+
+### 代理如何采取行动
+
+- **邮件操作** - 存档、垃圾箱、星标、标记已读、发送、草稿 - 全部作为 `templates/mail/actions/` 下的 `pnpm action <name>` 脚本运行。
+- **导航** — 为了打开线程或切换视图，代理会写入 `application_state.navigate`，UI 会使用并删除它。 `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` 作为一个简短示例，或者查看 `templates/mail/actions/manage-automations.ts` 作为具有多个子 actions 的示例。有关完整模式，请参阅 [actions](/docs/actions) 文档。
+
+**更改 UI。** 路由位于 `templates/mail/app/routes/` 中，组件位于 `templates/mail/app/components/email/` 和 `templates/mail/app/components/layout/` 中。该应用程序使用 `app/components/ui/` 和 Tabler 图标中的 shadcn/ui 原语 - 坚持这些。
+
+**更改代理的行为方式。**代理指导位于 `templates/mail/AGENTS.md` 中，skills 位于 `templates/mail/.agents/skills/` 中（`email-drafts`、`real-time-sync`、`security`、`self-modifying-code` 等）。代理行为是通过编辑 markdown 来更改的，而不是代码。
+
+**更改数据或设置。**跟踪表和相关结构的架构位于 `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)。