pipa-time-tracking

Pipa 时间跟踪

用户时间跟踪需求 -> Pipa 凭据 -> 通用 time_tracking/time_entry 工具记录。

重要：只能通过通用 Pipa Agent 工具记录 API 使用 Toggl 风格的时间记录。不要使用 Clockify、Toggl、截图、薪资、开票、生产力评分、被动活动重建或 /v1/time-tracking/* 包装端点。

保持简短待办列表：模式、凭据、待确认问题、载荷验证、API 调用、最终回复。

工作流

1. 选择模式。 只能选择一种。

   • 启动计时器："start tracking this"、"start timer for Acme"、"track time on frontend fixes" -> start。
   • 切换工作："switch to Acme QA" -> switch。
   • 停止当前计时器 -> stop。
   • 询问正在运行什么 -> current。
   • 记录过去的时间："log 45 minutes from 9 to 9:45" -> backfill。
   • 显示记录 / 汇总时间 -> review。
   • 更新/删除/取消/归档记录 -> update/archive。
   • 购买额度/充值、查看额度余额，或变更请求失败并返回 insufficient_credits -> top-up。
   • 薪资、开票、截图、被动重建、外部跟踪器同步、定期计时器、自动闲置检测 -> 说明 V1 不支持，然后停止。

   如果对话中已有成功的 API 响应，且用户询问该结果，则根据已知响应回答。不要调用不受支持的报告端点。

2. 加载凭据。 调用 API 前必须具备：

   • PIPA_API_BASE_URL
   • PIPA_API_KEY
   • PIPA_EMAIL
   • PIPA_USER_TIMEZONE

   别名：

   • PIPA_FOLLOW_UP_API_KEY -> PIPA_API_KEY
   • PIPA_FOLLOW_UP_EMAIL -> PIPA_EMAIL
   • 如果同一来源中同时存在规范名称和别名的值，则以规范名称为准。

   查找顺序：

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

   隐藏路径规则：

   • 不要依赖 glob/文件搜索查找 .pipa/credentials；隐藏目录可能被跳过或错误处理。
   • 直接检查明确路径：<workspace-root>/.pipa/credentials，然后是 ~/.pipa/credentials。
   • Shell 辅助脚本：从 cwd 或 git rev-parse --show-toplevel 解析根目录；读取 Path(root) / ".pipa" / "credentials"。
   • glob 对 .pipa/credentials 返回 No files found 并不能说明文件不存在。向用户索要凭据前先直接读取。

   凭据文件使用 dotenv 格式，不是 JSON：

   PIPA_API_BASE_URL=https://pailflow-chat-gateway.fly.dev
   PIPA_API_KEY=<API_KEY>
   PIPA_EMAIL=<EMAIL>
   PIPA_USER_TIMEZONE=<IANA_TIMEZONE>
   

   旧版格式：

   PIPA_API_BASE_URL=https://pailflow-chat-gateway.fly.dev
   PIPA_FOLLOW_UP_API_KEY=<API_KEY>
   PIPA_FOLLOW_UP_EMAIL=<EMAIL>
   PIPA_USER_TIMEZONE=<IANA_TIMEZONE>
   

   尽可能避免在聊天/日志/Markdown/shell 历史记录/进程参数中暴露 API 密钥。Shell 辅助脚本应在脚本内部读取凭据；只打印非机密结果。

   如果存在 PIPA_API_BASE_URL 和 API 密钥，则继续执行所选模式。如果该模式需要解释本地日期，而时区缺失，则进入第 3 步。

3. 仅在需要时补齐缺失凭据。 只补齐最少的缺项。

   • 缺少 PIPA_USER_TIMEZONE，且涉及本地日期/模糊时间 -> 原样询问：What timezone should I use? 然后停止。
   • 缺少 PIPA_API_BASE_URL -> 默认使用 https://pailflow-chat-gateway.fly.dev，除非用户指定了其他网关。
   • 缺少 PIPA_API_KEY 和 PIPA_FOLLOW_UP_API_KEY -> 询问用户的电子邮箱。

   电子邮件验证码设置：

   1. 说明电子邮件验证码验证会创建/替换 Pipa Agent 工具密钥。仅当用户可能已有密钥时，提及密钥替换会撤销旧密钥。
   2. 使用产品 agent-utilities 调用 POST /v1/key/email-code/start。
   3. 询问一次性电子邮件验证码。
   4. 使用 challenge id、验证码和产品 agent-utilities 调用 POST /v1/key/email-code/verify。
   5. 保存返回的密钥，除非环境变量是临时的、用户选择不保存，或写入失败。
   6. 仓库本地技能优先使用仓库本地 .pipa/credentials；全局技能使用 ~/.pipa/credentials。
   7. 写入仓库本地文件前，确保 .pipa/ 已加入 gitignore。文件权限设为 600。
   8. 告知用户存储路径。除非用户明确要求，否则绝不打印密钥。
   9. 重新加载凭据，继续执行所选模式。

4. API 约定。 只能使用：

   • GET /v1/agent-utility-records
   • POST /v1/agent-utility-records
   • GET /v1/agent-utility-records/:id
   • PATCH /v1/agent-utility-records/:id
   • DELETE /v1/agent-utility-records/:id
   • POST /v1/key/email-code/start
   • POST /v1/key/email-code/verify
   • POST /v1/topups/checkout-sessions

   积分余额：

   • 不要编造余额端点。仅当获准的 API 响应包含 credits_remaining 时，才能得知当前积分余额。
   • 如果用户询问余额，而最新的获准响应中没有 credits_remaining，请说明该技能无法直接查询当前余额。
   • 如果 insufficient_credits 包含 topup_limits，请在下一步操作中使用这些限制。
   • 将结账 URL 视为需要用户操作的付款链接。除非用户明确要求，否则不要保存这些链接，也不要直接输出很长的结账 URL。

   此技能使用的列表查询参数：

   • utility_type
   • record_type
   • status
   • started_at_gte
   • started_at_lt

   除非 API 响应或文档明确支持，否则不要使用其他列表筛选条件。如果无法筛选已归档记录，则在获取记录后排除已归档记录。

   身份验证标头：

   Authorization: Bearer ${PIPA_API_KEY}
   

   时间条目记录：

   {
     "utility_type": "time_tracking",
     "record_type": "time_entry",
     "status": "running",
     "title": "Work description",
     "started_at": "2026-06-30T13:00:00.000Z",
     "project_label": "optional project",
     "client_label": "optional client",
     "flex_label": "optional tag/task/phase",
     "rate_amount": 150,
     "rate_currency": "USD",
     "metadata": { "notes": "optional extras" }
   }
   

   规则：

   • running 必须包含 started_at，且省略 ended_at。
   • completed 必须包含 started_at 和 ended_at。
   • ended_at 必须大于或等于 started_at。
   • 每位用户只能有一个未归档的运行中 time_tracking/time_entry。
   • 删除操作会将记录归档。不要声称这是硬删除。
   • 精确保留时间戳。仅在面向用户的回复中对时长进行取整。

5. 开始模式。

   1. 标题取自请求。如果用户只说“开始计时”，则使用 Untitled work。
   2. 仅解析明确的标签：项目、客户、任务／标签／阶段。不要编造标签。
   3. GET /v1/agent-utility-records?utility_type=time_tracking&record_type=time_entry&status=running。
   4. 如果存在运行中的计时器，报告其 ID／标题／开始时间。原样询问：Do you want me to switch from that timer to [new title]? 然后停止。
   5. 如果没有运行中的计时器，则使用当前 UTC ISO 时间作为 started_at，创建 running 记录。
   6. 为创建操作使用新的 Idempotency-Key。
   7. 成功后 -> 执行第 14 步的开始模板。

   创建负载：

   {
     "utility_type": "time_tracking",
     "record_type": "time_entry",
     "status": "running",
     "title": "Acme frontend fixes",
     "started_at": "2026-06-30T13:00:00.000Z",
     "project_label": "Acme",
     "client_label": "Acme Co",
     "flex_label": "frontend"
   }
   

6. 切换模式。

   1. 按照第 5 步获取运行中的计时器。
   2. 如果没有，则通过开始模式创建新的运行中计时器。说明没有停止之前的计时器。
   3. 如果存在，则将其更新为 status=completed，并设置 ended_at=now。
   4. 停止成功后，使用新的 Idempotency-Key 创建新的运行中计时器。
   5. 如果停止成功但创建失败，原样说明这一情况，并报告没有新的计时器在运行。
   6. 返回已停止计时器的时长和新运行记录的 ID。

7. 停止模式。

   1. 按照第 5 步获取运行中的计时器。
   2. 如果没有，则说明当前没有运行中的计时器，然后停止。
   3. 更新运行中的记录：status=completed，ended_at=now。
   4. 确认 ID、标题、开始时间、结束时间、时长和标签。

   更新负载：

   { "status": "completed", "ended_at": "2026-06-30T14:15:00.000Z" }
   

8. 当前状态模式。

   1. 按照第 5 步获取运行中的计时器。
   2. 如果没有，则说明当前没有运行中的计时器。
   3. 如果存在，则报告 ID、标题、开始时间、已用时长和标签。
   4. 不要创建、停止或修改记录。

9. 补录模式。

   1. 使用 PIPA_USER_TIMEZONE 确定日期／时间范围。
   2. 如果日期／时间／时长／时区不明确，则直接提出一个澄清问题，然后停止。
   3. 将 started_at／ended_at 转换为 UTC ISO 格式。
   4. 创建 completed 记录。
   5. 返回已创建条目的确认信息。

   如果用户说“从 9:00 开始记录 45 分钟”，且时区／日期已知，则立即计算结束时间。无需额外确认。

10. 审查模式。

    1. 将范围解析为具体的 UTC ISO started_at_gte 和 started_at_lt。对于“今天”，使用 PIPA_USER_TIMEZONE。
    2. 使用 utility_type=time_tracking、record_type=time_entry 和范围筛选条件调用 GET /v1/agent-utility-records。
    3. 除非用户询问已归档／已取消的记录，否则排除已归档记录。
    4. 对响应中的记录分组／汇总。不要调用或编造报告端点。
    5. 将运行中的条目单独列出；其时长会变化。

11. 更新／归档模式。

    1. 从请求、上下文或简短候选列表中解析记录 ID。
    2. 引用有歧义 -> 直接提问一个问题，然后停止。
    3. 对标题、时间戳、标签、费率、元数据使用 PATCH /v1/agent-utility-records/:id。
    4. 仅在用户明确要求删除/取消/移除/归档时使用 DELETE /v1/agent-utility-records/:id。
    5. 归档运行中的计时器 -> 说明已取消/归档，而非已完成。

12. 充值模式。

    Time Tracking 使用 30 天需支付 10 Pipa 积分。不会自动续费；过期后下一次执行修改操作时会再次收取访问通行费。

    余额可见性：

    • 除非允许的响应中包含 credits_remaining，否则此技能无法查询当前积分余额。
    • 如果用户询问自己有多少积分，而当前响应中没有 credits_remaining，请说明这一点，并提供正在使用的网关 URL。
    1. 遇到 insufficient_credits 或用户要求购买/充值时使用。
    2. 选择用户要求的整数积分数量。
    3. 未提供数量 -> 原样询问：How many Pipa credits do you want to buy? 然后停止。
    4. 使用 { "credits": amount } 调用 POST /v1/topups/checkout-sessions。
    5. 将 checkout_url 作为 Markdown 链接分享，例如 [Open checkout](...)，并注明数量。
    6. 如果无法使用结账功能，且 API 仅提供 billing_url，则分享账单备用链接。
    7. 确认付款后，重试原始修改请求。

    如果 insufficient_credits 或 invalid_topup_credits 返回了限制条件，请遵照使用。示例：10 credits is below the minimum. Smallest top-up is 100 credits for $10. Want me to create that checkout session?

13. API 失败。 执行最小的后续操作。

    • running_timer_exists：获取运行中的计时器，说明情况，并询问是否切换。
    • insufficient_credits：执行步骤 12。
    • invalid_api_key：说明更换密钥会轮换账户密钥，执行步骤 3。
    • started_at_required、completed_entry_requires_ended_at、running_entry_cannot_have_ended_at、ended_at_before_started_at：修正请求载荷；仅在用户要求的时间有歧义时提问。
    • agent_utility_record_not_found：询问记录 ID；如果用户问的是“那条记录”，则列出近期候选项。
    • invalid_topup_credits：根据 API 响应给出最小的有效后续操作。示例：10 credits is below the minimum. Smallest top-up is 100 credits for $10. Want me to create that checkout session? 除非无法使用结账功能，否则不要分享 billing_url。
    • failed_to_create_agent_utility_record、failed_to_patch_agent_utility_record、failed_to_archive_agent_utility_record：说明失败前是否有任何变更。不要假称计时器已变更。
    • 缺少 API 密钥：执行步骤 3。

    除非错误要求，否则不要从头重新启动完整工作流。

14. 报告。 简洁、可操作、可审计。

    开始模板：

    Started the timer.
    
    - Record ID: `[id]`
    - Title: `[title]`
    - Started: `[started_at]`
    - Labels: `[project/client/flex or none]`
    

    停止模板：

    Stopped the timer.
    
    - Record ID: `[id]`
    - Title: `[title]`
    - Time: `[started_at]` to `[ended_at]`
    - Duration: `[rounded duration]`
    - Labels: `[project/client/flex or none]`
    

    规则：

    • 仅询问缺失或有歧义的必需信息。
    • 每次只问一个直接的后续问题。
    • 不要倾倒 API 元数据。
    • 不要在技能文件中存储机密。
    • API 返回剩余积分时，注明剩余积分。
    • 失败时，说明失败前是否有任何记录发生变更。