# 上岛记实时活动 Skill / PinToIsland Live Activity Skill

网页安装教程：

https://shangdaoji.com/skill/

本文档面向兼容 skill 的 AI 助手，用于通过用户授权的 `p2ia_...` token 在其设备上创建上岛记（PinToIsland）实时活动。App 内授权页可能仍显示 `AI Agent 授权` 或 `AgentToken`，实际 token 以 `p2ia_` 开头。

AI 助手只需要提交业务字段，例如取餐码、取件码、店名、商品名、二维码内容和开始时间。实时活动的内部结构由上岛记服务端维护，助手不应请求、展示或构造内部 Live Activity payload。

## 适合的 Agent 场景

Agent 可以把临时但需要随手查看的信息推到实时活动。除取餐码和取件码外，也适合用 `note` 类型创建这些提醒：

- 每日天气早报：每天早上把天气、温度、降雨概率和穿衣建议放到锁屏或灵动岛。
- 日程出发提醒：会议、看电影、赶车前，把地点、时间和注意事项放到实时活动。
- 喝水、吃药、复查等短提醒：用简短标题、正文和 emoji 图标保持可扫读。

这类场景不要构造内部实时活动字段，统一发送 `type: "note"`、`title`、`content`、`noteIcon` 和 `start_time`。

## 发给 AI 助手的指令

首次使用时，将下面这段话连同用户自己的 `p2ia_...` token 发给 AI 助手：

```text
请阅读 https://shangdaoji.com/agent.md 文档。如支持 Codex plugin，请安装 GitHub marketplace：wulonglin/shangdaoji-live-activity。请保存我的上岛记实时活动 token：<p2ia_token>。
```

## Codex 安装

```bash
codex plugin marketplace add wulonglin/shangdaoji-live-activity
codex plugin add shangdaoji-live-activity@pintoisland
```

## 通用 Skill 安装

```bash
mkdir -p ~/.codex/skills
curl -L https://shangdaoji.com/agent.skill.zip -o /tmp/shangdaoji-live-activity.skill.zip
unzip -o /tmp/shangdaoji-live-activity.skill.zip -d ~/.codex/skills
```

安装后开启新的会话，先说：

```text
请保存这个上岛记实时活动 token：<p2ia_token>
```

## API

```text
POST https://wulonglin.xyz/api/agent_activity.php
Authorization: Bearer <p2ia_token>
Content-Type: application/json
```

## 快捷指令 / 自动化

快捷指令、n8n、Make、Zapier 或普通脚本不需要安装 skill。只要能发 HTTP POST、设置 `Authorization` Header 和 JSON 请求体，就能直接调用同一个接口。

在快捷指令里可用「获取 URL 内容」：

- URL：`https://wulonglin.xyz/api/agent_activity.php`
- 方法：`POST`
- Header：`Authorization: Bearer <p2ia_token>`
- Header：`Content-Type: application/json`
- 请求体：JSON

最小请求：

```json
{
  "type": "meal",
  "pickup_code": "A123"
}
```

## 取餐码

```json
{
  "type": "meal",
  "pickup_code": "A123",
  "restaurant_name": "瑞幸咖啡",
  "product_name": "生椰拿铁",
  "qr_code_content": "可选，取餐二维码内容",
  "start_time": "now"
}
```

字段说明：

- `pickup_code` 必填，取餐码或叫号号。
- `restaurant_name` 可选，店名或品牌名。
- `product_name` 可选，商品名。
- `qr_code_content` 可选，取餐二维码原始内容。
- `start_time` 可选，支持 `now`、`YYYY-MM-DD HH:mm:ss` 或可被服务端识别的时间文本。

## 取件码

```json
{
  "type": "courier",
  "pickup_code": "8-1234",
  "station_name": "菜鸟驿站",
  "courier_brand": "顺丰",
  "address": "可选，取件地址",
  "start_time": "now"
}
```

## 笔记提醒

```json
{
  "type": "note",
  "title": "会议出发提醒",
  "content": "14:00 在滨江会议室开会，建议 13:30 出发。",
  "noteIcon": "🚕",
  "start_time": "YYYY-MM-DD 13:30:00"
}
```

`noteIcon` 可选，用于 note 类型的提醒图标，推荐传 emoji。`title` 默认使用简洁纯文本，不要重复放入同一个 emoji；只有用户明确要求时才在标题中保留 emoji。

天气早报示例：

```json
{
  "type": "note",
  "title": "每日天气早报",
  "content": "今天多云转小雨，18-24°C，午后降雨概率 70%，出门带伞。",
  "noteIcon": "🌦️",
  "start_time": "YYYY-MM-DD 07:30:00"
}
```

`YYYY-MM-DD 07:30:00` 由 Agent 按用户所在日期替换为下一次早报时间；如果用户说“每天”，Agent 需要每天按下一次 07:30 重新创建。

## 请求示例

```bash
curl -X POST "https://wulonglin.xyz/api/agent_activity.php" \
  -H "Authorization: Bearer <p2ia_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "meal",
    "pickup_code": "A123",
    "restaurant_name": "瑞幸咖啡",
    "product_name": "生椰拿铁",
    "start_time": "now"
  }'
```

## 响应

```json
{
  "success": true,
  "activity_id": 123,
  "type": "meal",
  "scheduled_at": "2026-06-27 12:00:00",
  "status": "pending",
  "status_url": "https://wulonglin.xyz/api/agent_activity.php?activity_id=123"
}
```

创建是异步执行。Agent 应使用相同的 `Authorization` 请求 `status_url`，确认状态后再向用户报告已送达：

```bash
curl "https://wulonglin.xyz/api/agent_activity.php?activity_id=123" \
  -H "Authorization: Bearer <AgentToken>"
```

如果返回 `action_required: "open_app_refresh_token"`，Agent 必须把 `user_message` 原样转告用户，提醒其打开上岛记 App 自动上传新令牌，然后重新发送。

## 取消或结束实时活动

未开始、仍在排程中的任务可以通过返回的 `activity_id` 取消：

```bash
curl -X POST "https://wulonglin.xyz/api/agent_activity.php" \
  -H "Authorization: Bearer <p2ia_token>" \
  -H "Content-Type: application/json" \
  -d '{"action":"cancel","activity_id":123}'
```

已经出现在锁屏或灵动岛上的实时活动，应使用 `end` 结束：

```bash
curl -X POST "https://wulonglin.xyz/api/agent_activity.php" \
  -H "Authorization: Bearer <p2ia_token>" \
  -H "Content-Type: application/json" \
  -d '{"action":"end","activity_id":123}'
```

如果返回 `activity_end_token_missing`，说明 App 还没有上传 end token，暂时无法远程结束；可先打开上岛记 App 后重试，或在 iPhone 上手动划掉。返回 410 表示该活动已经在设备上消失。

## 更新实时活动

已启动的任务可以通过返回的 `activity_id` 更新；请求仍然只传业务字段：

```bash
curl -X POST "https://wulonglin.xyz/api/agent_activity.php" \
  -H "Authorization: Bearer <p2ia_token>" \
  -H "Content-Type: application/json" \
  -d '{"action":"update","activity_id":123,"type":"meal","pickup_code":"B456","restaurant_name":"瑞幸咖啡"}'
```

高频静默更新可传 `priority: 5`。需要提示音和弹岛时传 `sound: true`；可选传 `alert_title` / `alert_body` 覆盖提示文案。

如果活动尚未启动，或 App 尚未上传 update token，会返回 `activity_update_token_missing`。