pipa-follow-up-reminders

Pipa 后续提醒

用户的提醒请求 -> 已验证的电子邮箱 + 已确定的时间 -> Pipa 单次电子邮件提醒。

重要：只能通过 https://pailflow-chat-gateway.fly.dev 创建或取消确定的单次电子邮件提醒。提醒只能发送到与 API 密钥关联的已验证邮箱。不要虚构列表、读取、更新、暂停、恢复、重复提醒、收件箱监控、回复检测、短信、Slack、Gmail 定时发送或任意收件人相关流程。

执行此技能时，请维护一份简短的待办列表，以保持上下文清晰：模式、凭据、如有则记录缺少的问题、负载验证、API 调用、最终回复。

工作流

1. 选择模式。

   只能选择一种模式。

   • 用户要求未来通过电子邮件提醒，例如“明天发邮件提醒我”“通过电子邮件提醒我”或“两小时后跟进我” -> 创建模式。继续步骤 2。
   • 用户要求取消已安排的 Pipa Follow-Up 提醒 -> 取消模式。继续步骤 2。
   • 用户要求购买额度、充值，或创建请求失败并返回 insufficient_credits -> 充值模式。继续步骤 2。
   • 用户要求列出提醒、更新提醒、重复提醒、监控收件箱、检测回复、Gmail 定时发送、短信、Slack，或提醒其他人 -> 说明 V1 不支持此流程，然后停止。

   跳转：如果对话中已有成功的 API 响应，且用户询问该结果，则根据已知响应回答。不要调用不受支持的读取/列表 API。

2. 加载凭据。

   API 调用前加载以下值。区分持久用户凭据与托管运行凭据：

   • PIPA_FOLLOW_UP_API_KEY
   • PIPA_FOLLOW_UP_EMAIL
   • PIPA_USER_TIMEZONE

   查找顺序：

   1. 网关注入的值。
   2. 环境变量。
   3. 仓库本地 .pipa/credentials。
   4. 用户全局 ~/.pipa/credentials。

   凭据规则：

   • pipa_agent_v1.* 密钥是托管运行凭据，不是持久用户密钥。
   • 它们可能会过期。如果其中一个失效，应说明托管运行凭据已过期，而不是用户的提醒凭据已过期。
   • 不要自行将 pipa_agent_v1.* 密钥写入用户管理的凭据文件。
   • 如果用户管理的凭据文件中有已过期的 pipa_agent_v1.* 密钥，请忽略/移除该密钥，并在开始电子邮件验证码设置前继续查找。
   • 电子邮件验证码验证会返回持久用户密钥。这些才是应为本地/持久技能使用而存储的密钥。

   凭据文件格式：

   PIPA_FOLLOW_UP_API_KEY=<API_KEY>
   PIPA_FOLLOW_UP_EMAIL=<EMAIL>
   PIPA_USER_TIMEZONE=<IANA_TIMEZONE>
   

   尽可能避免将 API 密钥写入聊天、日志、Markdown 输出、Shell 历史记录和进程参数。

   跳转：如果三个值都已提供，请直接转到所选模式对应的步骤：创建模式转到步骤 4，取消模式转到步骤 7，充值模式转到步骤 8。

3. 仅在需要时设置缺失的凭据。

   只补全缺少的最小部分。如果只缺少一个值，不要重新开始设置。

   • 如果缺少 PIPA_USER_TIMEZONE，但已有密钥和电子邮箱，则原样询问：What timezone should I use? 等待用户回答后再继续。
   • 如果缺少 PIPA_FOLLOW_UP_API_KEY 或 PIPA_FOLLOW_UP_EMAIL，则询问用户的电子邮箱。

   电子邮件验证码设置：

   1. 说明电子邮件验证码验证会创建或替换密钥。仅当用户可能已经拥有密钥时，才提及替换密钥会撤销之前的密钥。
   2. 使用产品 follow-up 调用 POST /v1/key/email-code/start。
   3. 请用户提供邮件中的一次性验证码。
   4. 使用挑战 ID、验证码和产品 follow-up 调用 POST /v1/key/email-code/verify。
   5. 存储返回的持久密钥，除非环境是临时的、用户选择不存储，或写入失败。不要自行写入 pipa_agent_v1.* 密钥。
   6. 对于全局安装的技能，优先使用 ~/.pipa/credentials。对于仓库本地技能，优先使用仓库本地的 .pipa/credentials。
   7. 写入仓库本地凭据之前，确保 .pipa/ 已加入 gitignore。使用文件权限 600。
   8. 告知用户凭据的存储位置。除非用户明确要求，否则绝不要打印密钥。
   9. 返回步骤 2，重新加载凭据，然后继续所选模式。

4. 创建模式：准备提醒载荷。

   必需的载荷字段：

   • recipient_email：使用 PIPA_FOLLOW_UP_EMAIL 或已验证凭据中的邮箱。
   • due_at：未来的 UTC ISO 时间戳。
   • timezone：用于解释时间的 IANA 时区。
   • subject：用户提供的明确主题，或 Reminder from Pipa。
   • body_text：仅包含纯文本提醒正文。

   按确定性方式构建载荷：

   1. 将 recipient_email 设置为 PIPA_FOLLOW_UP_EMAIL。
   2. 如果用户要求使用其他收件人，请停止并说明 V1 仅支持已验证密钥所有者。询问是否改用已验证的邮箱。
   3. 解析时间之前，先规范化用于解释时间的时区：
      • 如果用户说 Eastern、ET、EST 或 EDT，且指的是美国东部时间，则使用 America/New_York。
      • 不要将口语中的 EST 映射到 America/Panama 等固定偏移时区；必须通过 IANA 时区处理夏令时。
      • 如果用户明确要求固定偏移时区，请使用正确的固定偏移 IANA 时区，并在确认信息中说明。
   4. 使用规范化后的 IANA 时区，将用户要求的时间解析为 due_at，即未来的 UTC ISO 时间戳。
      • 对于 today、tomorrow、星期几和明确日期，先将当前时刻转换为用于解释时间的时区，再以该时区的日历日期为基准。不要使用 UTC 日期作为当地日期。
      • 对于明确日期加具体时间的请求，在调用 API 之前，确认解析得到的当地日期和时间与用户所说的一致。
      • 如果用户要求的当地时间今天已经过去，请进行一次澄清，不要默默将提醒安排到明天。
   5. 如果时间含糊，请直接提出一个澄清问题，并在用户回答前停止。
   6. 将 timezone 设置为用于解释时间的规范化 IANA 时区。
   7. 如果用户提供了明确主题，则将 subject 设置为该主题；否则使用 Reminder from Pipa。
   8. 如果用户提供了提醒文本，则将 body_text 设置为该文本；否则使用简洁的纯文本提醒正文。

   时间示例：

   • 当前 UTC 时间为 2026-07-17T00:57:00Z，用户时区为 America/New_York，请求为 tomorrow at 7am -> 当地基准日期为 7 月 16 日，因此 due_at 为 2026-07-17T11:00:00.000Z。
   • 当前 UTC 时间为 2026-07-17T13:01:00Z，美国东部地区用户请求 July 17 9:10 AM EST -> 使用 America/New_York，因此 due_at 为 2026-07-17T13:10:00.000Z，而不是 14:10Z。

   跳过后续步骤：如果用户说“5 分钟后”“两小时后”或其他相对时长，且时区已知，则立即计算。不要要求确认。

5. 创建模式：调用 API 之前进行验证。

   验证将要发送的确切 JSON 载荷：

   1. 确认 recipient_email、due_at、timezone、subject 和 body_text 均已提供。
   2. 确认每个必填字段都是非空字符串。
   3. 确认 due_at 是未来时间。
   4. 确认按 timezone 时区本地显示的 due_at 与请求的日期和时间一致。
   5. 对于 30 分钟内到期的提醒，转换时间后比较当前时间与 due_at，并确认留有足够时间完成 API 创建和调度器派发。如果时间已过或在 60 秒以内，请要求用户提供新的时间。
   6. 如果验证失败，请先修正载荷构造，再调用 API。
   7. 使用 shell 命令构造 JSON 时，应先导出变量，再从子进程读取；或者在同一个运行时内构造时间戳和 JSON。
   8. 生成新的 Idempotency-Key。

   载荷结构：

   {
     "recipient_email": "[email protected]",
     "due_at": "2026-06-19T13:00:00.000Z",
     "timezone": "America/New_York",
     "subject": "Reminder from Pipa",
     "body_text": "Send the invoice to Acme."
   }
   

   跳转提示：如果验证通过，不要额外请求确认。创建提醒。

6. 创建模式：创建提醒。

   使用已验证的载荷调用一次 POST /v1/follow-up-reminders。

   请求头：

   Authorization: Bearer ${PIPA_FOLLOW_UP_API_KEY}
   Content-Type: application/json
   Idempotency-Key: <required for create only>
   

   成功时，返回：

   Scheduled the follow-up reminder.
   
   - Reminder ID: `[id]`
   - Recipient: `[recipient_email]`
   - Due: `[due_at]`
   - Timezone: `[timezone]`
   - Subject: `[subject]`
   - Credits remaining: `[credits_remaining]`
   

   如果 API 调用失败，转到步骤 9，并仅执行匹配的失败分支。

7. 取消模式：取消提醒。

   仅当用户要求取消已安排的 Pipa Follow-Up 提醒时才取消。

   1. 要求提供来自请求、对话或先前 API 响应的提醒 ID。
   2. 如果缺少提醒 ID，请向用户索要，并说明 V1 无法列出提醒。
   3. 仅当目标提醒不明确时才请求确认。
   4. 调用 DELETE /v1/follow-up-reminders/:id。
   5. 返回简短的取消确认。

   跳转提示：如果提醒 ID 已提供且没有歧义，请勿在删除前请求确认。

8. 充值模式：创建结账会话。

   如果创建提醒时返回 insufficient_credits，或用户要求购买额度，则使用此模式。

   1. 选择用户要求购买的整数额度。
   2. 如果用户未指定额度，请原样询问：How many Pipa credits do you want to buy? 在用户回答前停止。
   3. 使用额度调用 POST /v1/topups/checkout-sessions。
   4. 将返回的 checkout_url 作为 Markdown 超链接分享，使用简洁的链接文本（例如 [Open checkout](...)），并附上购买额度。除非用户明确要求完整 URL，否则不要直接输出冗长的结账 URL。
   5. 将结账 URL 视为需要用户操作的付款链接。不要持久化保存。
   6. 如果无法创建结账会话，且响应中仅包含 billing_url，则分享备用账单链接。
   7. 用户确认付款后，返回步骤 4，重试原提醒请求。

   请求结构：

   { "credits": 100 }
   

   跳转提示：如果因 insufficient_credits 进入此模式，请保留原始提醒请求，以便在付款确认后重试。

9. 处理 API 失败。

   根据返回的错误，仅执行最小的后续操作。

   • recipient_not_verified：询问是否改用 PIPA_FOLLOW_UP_EMAIL。
   • due_at_not_future：根据用户时区重新解析时间。仅在仍有歧义时询问。
   • invalid_api_key：如果密钥是已存储的 pipa_agent_v1.*，请忽略或移除该已存储密钥，并继续查找。如果是持久的邮箱验证码密钥，请说明替换密钥会轮换账户密钥，然后转到步骤 3。
   • pipa_agent_credential_expired：说明托管运行凭据已过期。继续查找持久密钥。仅当不存在持久密钥时，才开始邮箱验证码验证。
   • insufficient_credits：转到步骤 8。
   • invalid_topup_credits：给出最小的有效后续操作。例如：10 credits is below the minimum. Smallest top-up is 100 credits for $10. Want me to create that checkout session? 除非无法创建结账会话，否则不要分享 billing_url。
   • active_reminder_limit_reached：说明 V1 无法列出提醒；用户需要提供已知的提醒 ID 以便取消，或等待提醒发送。
   • 缺少 API 密钥：转到步骤 3。 跳过已完成的步骤：除非错误要求，否则不要重新启动整个工作流。

10. 报告结果。

    表述简洁、便于执行，并聚焦下一步行动。

    • 仅询问缺失或有歧义的必需信息。
    • 每次只提出一个直接的后续问题。
    • 不要在回复中向用户倾倒 API 元数据。
    • 不要在此技能文件中存储机密信息。
    • 如果 API 返回剩余积分数，请予以说明。