iGPT 邮件问答

针对用户邮件内容提出问题，并获得基于上下文的推理性、结构化回答。由 iGPT 的上下文引擎驱动，可跨时间重建对话、决策、责任归属与意图。

本技能功能

此技能通过调用 iGPT 的 recall/ask 接口，基于用户连接的邮件数据生成答案。与基础检索不同，上下文引擎具备以下能力：

• 跨回复、转发和抄送完整重建对话线程
• 识别谁做出了什么决定、谁负责什么事项、哪些任务仍待处理
• 从非结构化邮件中提取结构化数据（如任务、截止日期、联系人、风险）
• 支持多种质量层级以适应不同复杂度需求
• 返回文本、JSON 或符合 Schema 校验的结构化输出
• 支持流式传输（SSE），实现实时响应

适用场景

• 汇总单个线程或多个线程中的关键事件
• 提取行动项、决策结论或未决问题
• 分析交易或客户相关邮件中的情绪或风险
• 回答需要理解多封邮件上下文的问题
• 从邮件内容中生成结构化数据（JSON、Schema 校验）
• 基于近期通信内容准备会议简报

前置条件

1. 一个 iGPT API 密钥（可在 https://igpt.ai/hub/apikeys/ 获取）
2. 已连接的邮件数据源 —— 用户必须通过 connectors/authorize 完成 OAuth 授权后，ask 才能返回结果。可通过 datasources.list() 检查连接状态
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")

res = igpt.recall.ask(input="总结本周会议中的关键风险、决策和下一步行动。")
if res is not None and res.get("error"):
    print("iGPT 错误:", res)
else:
    print(res)

获取 JSON 输出

传入 output_format="json" 可获取非结构化 JSON；也可提供 Schema 实现结构化校验输出：

# 简单 JSON 输出
res = igpt.recall.ask(
    input="本周有哪些待办事项？",
    output_format="json"
)

# 结构化校验输出（带 Schema）
res = igpt.recall.ask(
    input="本周的待办事项",
    quality="cef-1-normal",
    output_format={
        "strict": True,
        "schema": {
            "type": "object",
            "required": ["action_items"],
            "additionalProperties": False,
            "properties": {
                "action_items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "required": ["title", "owner", "due_date"],
                        "properties": {
                            "title": {"type": "string"},
                            "owner": {"type": "string"},
                            "due_date": {"type": "string"}
                        }
                    }
                }
            }
        }
    }
)
print(res)

示例响应：

{
    "action_items": [
        {
            "title": "批准修订后的第一季度预算分配",
            "owner": "Dvir Ben-Aroya",
            "due_date": "2026-01-15"
        },
        {
            "title": "批准 FY2026 年最终战略重点",
            "owner": "董事会",
            "due_date": "2026-01-31"
        }
    ]
}

使用质量层级

iGPT 上下文引擎提供三个质量层级：

# 正常：快速响应，适用于简单问题
res = igpt.recall.ask(
    input="我下次与 Acme 公司的会议是什么时候？",
    quality="cef-1-normal"
)

# 高级：更深入推理，适合复杂多线程分析
res = igpt.recall.ask(
    input="目前与 Acme 公司的谈判进展如何？我们有哪些优势？",
    quality="cef-1-high"
)

# 推理：最大深度，用于复杂的跨线程整合分析
res = igpt.recall.ask(
    input="回顾过去一个季度与 Acme 的所有沟通，有哪些模式表明存在风险？我们应该如何应对？",
    quality="cef-1-reasoning"
)

流式响应

流式传输返回解析后的 JSON 数据块（字典），而非原始文本。需从每个数据块中提取内容：

stream = igpt.recall.ask(
    input="从首次接触到现在，详细说明 Acme 项目的时间线。",
    stream=True
)

for chunk in stream:
    if isinstance(chunk, dict) and chunk.get("error"):
        print("流式错误:", chunk)
        break
    # 每个数据块都是一个解析后的 JSON 字典
    print(chunk)

流式传输具有容错性：若连接中断，迭代器会返回错误数据块并正常结束，不会抛出异常。

在提问前检查数据源连接状态

# 验证用户是否已连接数据源
status = igpt.datasources.list()
if status is not None and not status.get("error"):
    print("已连接的数据源:", status)
else:
    # 首次连接数据源
    auth = igpt.connectors.authorize(service="spike", scope="messages")
    print("请打开以下链接完成授权:", auth.get("url"))

参数说明

错误处理

markdown

SDK 不会抛出异常，而是返回标准化的错误对象：

res = igpt.recall.ask(input="昨天董事会会议发生了什么？")

if res is not None and res.get("error"):
    error = res["error"]
    if error == "auth":
        print("检查您的 API 密钥")
    elif error == "params":
        print("检查您的请求参数")
    elif error == "network_error":
        print("网络问题 —— SDK 会在返回此错误前进行指数退避重试（默认 3 次）")
else:
    print(res)

外部接口

此技能仅与以下接口通信：

• https://api.igpt.ai/v1/recall/ask/ —— 推理接口
• https://api.igpt.ai/v1/connectors/authorize/ —— 仅在初始数据源连接设置时使用
• https://api.igpt.ai/v1/datasources/list/ —— 用于检查连接状态

不与其他外部接口通信。不向任何第三方服务发送数据。igptai PyPI 包源码可在 https://github.com/igptai/igpt-python 获取。

安全与隐私

• API 密钥作用域限制：所有请求通过 IGPT_API_KEY 以 Bearer Token 方式通过 HTTPS 认证。无 shell 访问、无文件系统访问、无系统命令执行。
• 用户隔离：每个查询均限定于特定的 user 标识符。用户 A 无法访问用户 B 的邮件数据。隔离在索引和执行层面强制实施，而非作为过滤层。
• OAuth 只读权限：邮件数据源连接使用具有只读权限的 OAuth。该技能不会发送、修改或删除邮件。
• 无数据留存：提示内容在执行后即被丢弃。记忆按需重建，不进行存储。
• 传输加密：所有通信均通过 HTTPS 进行。无明文接口。
• 无本地持久化：此技能不会写入磁盘、修改环境文件或创建持久配置，除标准的 IGPT_API_KEY 环境变量外。
• 内置重试机制：SDK 在返回 network_error 前，会对失败请求进行指数退避重试（默认 3 次，基础延迟 100ms，倍数因子 2）。

完整安全模型请参阅 https://docs.igpt.ai/docs/security/model。

此技能不执行的操作

• 不发送、修改、转发或删除邮件
• 不访问文件系统或执行 shell 命令
• 不安装持久服务或计划任务
• 不调用 api.igpt.ai 以外的接口
• 不将 API 密钥或 OAuth token 存储在环境变量之外

示例问题

以下均为自然语言提示，均可正常工作：

• "总结本周邮件线程中的主要风险" —— 跨线程分析
• "昨天董事会会议中有哪些待办事项？" —— 任务提取
• "Acme 项目当前进展如何？" —— 交易情报
• "预算审批由谁负责，截止时间是什么？" —— 所有权与截止日期提取
• "过去 7 天内是否有邮件语气明显转负面的线程？" —— 情感分析
• "为明天与 Sarah 的会议生成一份简报" —— 会议准备

资源

• 获取 API 密钥：https://igpt.ai/hub/apikeys/
• 文档：https://docs.igpt.ai
• API 参考：https://docs.igpt.ai/docs/api-reference/ask
• 在线体验：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/igpt-python