Gmail Lead Desk（gmail-lead-desk）📧

Gmail Lead Desk — 通过 AISA 网关实现的独立式销售与客户支持 Gmail 工作流。

仅需一项能力：连接 Gmail、运行白名单内工具、分类处理收件箱、草拟回复、归档成交线索 —— 无需其他技能。

快速开始

export AISA_API_KEY="your-key"   # 获取地址：https://aisa.one

起飞前检查（请务必优先执行，任一失败即中止）：

1. AISA_API_KEY 已设置 — 若未设置，请提示用户在调用任何 API 前完成配置。
2. user_id 已知 — 使用用户提供的 Gmail 地址。若尚未提供，请询问：“您希望使用哪个 Gmail 地址作为您的身份标识？”
3. Gmail 状态为 ACTIVE — 若 connected_account_id 缺失或非 ACTIVE，请先运行 Workflow 0。

• 基础 URL： https://api.aisa.one
• 认证方式： Authorization: Bearer $AISA_API_KEY
• Windows 环境： 请使用 curl.exe

OAuth 与 tools/execute 相关说明详见：references/connect_and_execute.md

适用场景

• 通过 OAuth 连接或重新连接 Gmail
• 扫描需跟进的 未读线索（unread leads）
• 汇总 咨询/支持类邮件线程（符合 CRM 格式）
• 基于销售模板 草拟 回复（默认不发送）
• 为已成交线索添加标签并 归档
• 用户提及关键词时触发：unanswered（未回复）、follow-up（需跟进）、inquiry（咨询）、quote（报价）、draft（草稿）、archive（归档）、lead（线索）、connect Gmail（连接 Gmail）

不适用场景

• 非 Gmail 应用（如 Slack、GitHub 等）—— 超出本模块范围
• 主动式新邮件自动化 —— 当前非 MVP 功能；详见 references/workflows.md § Future
• 批量永久删除、创建过滤器 —— 默认禁用，仅在用户明确请求时启用

用户意图 → 工作流速查表

若 Gmail 尚未连接（即无 ACTIVE 状态的 connected_account_id），请首先运行 Workflow 0。

Workflow 0 — 连接 Gmail（摘要）

1. GET /auth_configs?toolkit_slug=gmail → 获取 auth_config_id
2. GET /connected_accounts?toolkit_slugs=gmail&user_ids={user_id} — 若存在 ACTIVE 记录则复用
3. 否则需用户确认，再执行 POST /connected_accounts/link → 用户打开返回的 redirect_url
4. 每 3–5 秒轮询一次状态，直至 status 变为 ACTIVE；保存返回的 connected_account_id
   • 超时机制（约 2 分钟，共 24 次轮询）： 超时后停止轮询，并提示用户：“OAuth 未完成，请重试或检查浏览器标签页。”
   • 若状态为 DISCONNECTED 或 REVOKED：从第 3 步起重新执行。

完整步骤详见：references/connect_and_execute.md

核心工作流（摘要）

A — 未读线索扫描

1. 确认 connected_account_id（通过 Workflow 0）。
2. 调用 GMAIL_FETCH_EMAILS，使用销售场景默认查询条件 —— 具体参见 workflows.md。
3. 输出表格字段：发件人 | 主题 | 等待天数 | thread_id | 建议操作。
4. 本工作流结束时不得发送邮件。

B — 线程摘要（CRM 就绪格式）

1. 调用 GMAIL_FETCH_MESSAGE_BY_THREAD_ID；按 internalDate 升序排序。
2. 固定摘要段落：客户信息、需求、预算/时间线、下一步行动、附件（当附件为推断得出时，标注为 unverified）。

C — 模板化草稿（默认不发送）

1. 加载目标线程（同 B）；确认收件人、语气风格、是否引用报价/链接等。
2. 调用 GMAIL_REPLY_TO_THREAD 或 GMAIL_CREATE_EMAIL_DRAFT；若已指定 thread_id，则 主题字段留空。
3. 返回 draft_id 及预览内容。

C-send — 仅在用户明确要求时发送

• 用户明确表达 send / confirm send / send now 等指令。
• 展示完整的收件人（To）、抄送（Cc）、主题及正文；获得用户确认后，再调用 GMAIL_SEND_DRAFT 或 GMAIL_SEND_EMAIL。

D — 归档并打标签

1. GMAIL_LIST_LABELS → 仅提取以 Label_* 开头的标签 ID。
2. 如需新建标签，调用 GMAIL_CREATE_LABEL（需用户确认）。
3. 选取 ≤5 条 messageIds 样本并统计总数 → 调用 GMAIL_BATCH_MODIFY_MESSAGES 批量操作。

切勿猜测 tool_slug 值。 可用工具列表详见：references/tool_whitelist.md。

安全规范

Gmail 常见陷阱说明：references/gmail_gotchas.md。

参考文档路由

查找顺序： 用户意图 → 如需则先执行 Workflow 0 → workflows.md → tool_whitelist.md → GET /tools/{tool_slug} → POST /tools/execute/{tool_slug}。

故障排查