iGPT 邮件搜索

按语义（含义）而非仅关键词搜索用户的邮件。在用户完整的收件箱历史中，执行混合式语义 + 关键词检索。

该技能的功能

该技能调用 iGPT 的 recall/search 接口，从用户已连接的邮箱中查找相关邮件及会话线程。其搜索引擎具备以下能力：

• 融合语义向量搜索（理解语义）与关键词匹配（精准捕获指定术语）
• 覆盖用户全部已索引的邮件历史（不受某些服务商限制的 90 天时效约束）
• 支持日期范围过滤，满足时间限定类查询需求
• 返回按相关性排序的结果，并附带相关性评分
• 如邮件含附件，则一并返回附件引用信息

本技能仅执行检索操作：定位并返回原始邮件内容，不对其进行推理、摘要或结构化数据提取。如需上述高级分析能力，请使用配套技能 igpt-email-ask —— 该技能调用 iGPT 的 Context Engine，提供分析、摘要和结构化提取功能。

适用场景

• 查找关于特定主题、项目或人员的邮件
• 在指定日期范围内定位会话线程
• 获取原始邮件内容以供后续处理
• 将邮件上下文输入至其他工具或智能体（agent）步骤中
• 在执行操作前，快速了解某主题此前的讨论情况
• 拉取与特定联系人或公司最近的往来邮件

何时应改用 igpt-email-ask

若你需要的是摘要性或综合性的回答、结构化数据提取（例如任务、决策、联系人）、情感分析、跨多个会话线程的推理，或需深度理解而非简单定位的问题答案——请使用 igpt-email-ask，而非 search。

经验法则：若提示（prompt）是一个问题，使用 ask；若提示是一个查找请求，使用 search。

前提条件

1. iGPT API 密钥（获取地址：https://igpt.ai/hub/apikeys/）
2. 已连接的邮件数据源 —— 用户须先通过 connectors/authorize 完成 OAuth 授权，搜索才能返回结果
3. Python >= 3.8，并已安装 igptai 包

安装配置

pip install igptai

将你的 API 密钥设为环境变量：

export IGPT_API_KEY="your-api-key-here"

使用方法

基础用法：按主题搜索

from igptai import IGPT
import os

igpt = IGPT(api_key=os.environ["IGPT_API_KEY"], user="user_123")

results = igpt.recall.search(query="board meeting notes")
print(results)

返回与查询匹配的相关邮件及会话线程列表，按相关性降序排列。

带日期范围的搜索

将结果限定在特定时间窗口内：

results = igpt.recall.search(
    query="budget allocation",
    date_from="2026-01-01",
    date_to="2026-01-31"
)
print(results)

限制返回结果数量

results = igpt.recall.search(
    query="partnership proposals",
    max_results=10
)
print(results)

搜索特定人员的邮件

语义引擎可理解参与者上下文：

results = igpt.recall.search(
    query="emails from Sarah about the product launch",
    date_from="2026-01-01"
)
print(results)

与 ask 结合实现两步工作流

典型模式：先搜索以了解现有内容，再发起分析请求：

# 步骤 1：查找相关会话线程
results = igpt.recall.search(
    query="Acme Corp contract negotiation",
    max_results=20
)
print(f"Found {len(results)} relevant threads")

# 步骤 2：请求结构化分析
analysis = igpt.recall.ask(
    input="Summarize the current status of the Acme Corp contract negotiation. What are the open issues and who owns them?",
    output_format="json"
)
print(analysis)

参数说明

错误处理

SDK 采用“无异常抛出”（no-throw）模式：错误以返回值形式呈现，而非抛出异常：

results = igpt.recall.search(query="Q4 planning")

if isinstance(results, dict) and results.get("error"):
    error = results["error"]
    if error == "auth":
        print("Check your API key")
    elif error == "params":
        print("Check your request parameters")
    elif error == "network_error":
        print("Network issue, retry")
else:
    for result in results:
        print(result)

外部端点

该技能仅与以下端点通信：

• https://api.igpt.ai/v1/recall/search —— 搜索接口
• https://api.igpt.ai/v1/connectors/authorize —— 仅在初始数据源连接配置阶段调用

不访问任何其他外部端点，亦不向任何第三方服务发送数据。igptai PyPI 包源码位于 https://github.com/igptai/igptai-python。

安全与隐私

• API 密钥作用域隔离：所有请求均通过 HTTPS 以 Bearer Token 方式携带 IGPT_API_KEY 进行身份认证。不涉及 Shell 访问、文件系统访问或系统命令执行。
• 用户级数据隔离：每次查询均绑定特定 user 标识符。用户 A 无法访问用户 B 的邮件数据。该隔离机制在索引层与执行层原生实现，而非依赖后置过滤。
• OAuth 只读权限：邮件数据源连接采用 OAuth 协议，且仅申请只读权限。本技能不会发送、修改或删除任何邮件。
• 无数据留存：提示（prompt）在执行完毕后即被丢弃。上下文内存按需重建，不作持久化存储。
• 传输加密：所有通信均通过 HTTPS 加密进行，不存在明文通信端点。
• 无本地持久化：本技能不会写入磁盘、修改环境配置文件，也不会在标准 IGPT_API_KEY 环境变量之外创建任何持久化配置。

完整安全模型详见：https://docs.igpt.ai/docs/security/model。

与基础邮件搜索的区别

示例查询语句

以下均为有效的自然语言查询：

• "board meeting notes" —— 即使邮件正文中未出现该确切短语，也能查找到关于董事会会议的邮件
• "emails about the product launch timeline" —— 对主题具备语义理解能力
• "anything from legal about compliance" —— 可识别部门（legal）与主题（compliance）上下文
• "invoices from Q4 2025" —— 同时结合主题与隐含的时间上下文
• "conversations where deadlines were mentioned" —— 支持概念级检索

配套技能

两个技能共用同一 IGPT_API_KEY 和已连接的数据源。建议同时安装二者，以构建完整的「搜索 → 分析」工作流。

资源链接

• 获取 API 密钥：https://igpt.ai/hub/apikeys/
• 文档中心：https://docs.igpt.ai
• API 参考手册：https://docs.igpt.ai/docs/api-reference/search
• 交互式 Playground：https://igpt.ai/hub/playground/
• Python SDK：https://pypi.org/project/igptai/
• Node.js SDK：https://www.npmjs.com/package/igptai
• GitHub 仓库：https://github.com/igptai/igptai-python