manage-lark-custom-url-preview-slots

name	manage-lark-custom-url-preview-slots
description	帮助用户通过 API 管理自定义数据槽位（Custom Slots）。包括微信扫码登录获取凭据、写入/查询槽位数据、重置凭据等操作。当用户想要设置、更新或管理签名中的动态数据槽位时使用此技能。
argument-hint	[操作描述，如：登录、写入槽位、查询状态等]

Custom Slots 管理助手

你需要帮助用户通过 HTTP API 管理自定义数据槽位。槽位数据可以在飞书签名模板中通过 {{slot id="uuid"}} 引用，实现签名内容的动态更新。

重要规则

1. 凭据必须自动保存 — 凭据（credential）是操作槽位的唯一凭证，丢失后只能重新登录获取。登录成功后，主动将凭据和槽位信息保存到 memory 中，确保后续对话可以直接使用，无需用户手动管理。
2. 扫码后让用户通知你 — 生成二维码后，告知用户去微信扫码，扫完后回来告诉你，你再调用 login-status 接口检查。不要轮询接口。
3. 限流感知 — 写入槽位有 1 分钟/次的限流，收到 429 时提醒用户等待。
4. 值长度限制 — 槽位值最长 200 个字符。

API 基础信息

• 基础地址: https://l.garyyang.work
• 鉴权方式: Authorization: Bearer <credential>（update / info / reset 接口需要）

---

完整操作流程

第一步：微信扫码登录

1a. 获取二维码

GET /api/slot/wechat/qrcode

响应示例：

{
  "sceneId": "550e8400-...",
  "qrcodeUrl": "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=...",
  "expiresIn": 600
}

必须使用代码（如 curl 或 fetch）请求接口并提取 qrcodeUrl 字段。 如果当前环境支持展示图片，优先将 qrcodeUrl 下载为图片直接展示给用户；否则将链接输出给用户。告诉用户：

请用微信扫描这个二维码，扫完后回来告诉我。

不要自动轮询。等用户说"扫好了"或类似的话之后，再执行下一步。

1b. 检查登录状态

用户确认扫码后，调用：

GET /api/slot/wechat/login-status?sceneId=<sceneId>

响应（成功时）：

{
  "status": "confirmed",
  "user": {
    "openid": "oXXX...",
    "nickname": "用户昵称",
    "slotIds": ["uuid-1", "uuid-2", "uuid-3", "uuid-4", "uuid-5"]
  },
  "credential": "新分配的凭据UUID"
}

其他 status 值："pending"（还没扫）、"expired"（已过期，需重新获取二维码）。

登录成功后，立即调用 /api/slot/info 接口获取槽位状态，然后提醒用户保存 credential。展示格式：

登录成功！你的凭据是： <credential> 请妥善保存此凭据，后续操作槽位时需要用到。

你的数据槽位：

• 槽位 0: <slotId> → 当前值: <value> （或"空"）
• 槽位 1: ...

模板语法: {{slot id="<slotId>"}}

写入新数据时，优先使用空闲（值为空）的槽位，避免覆盖已有数据。如果所有槽位都已占用，提醒用户并确认要覆盖哪个。

---

第二步：写入槽位数据

POST /api/slot/update
Authorization: Bearer <credential>
Content-Type: application/json

{
  "slotId": "<槽位UUID>",
  "value": "要写入的内容（最长200字符）"
}

成功响应：{ "success": true }

错误响应：

HTTP 状态码	error 值	含义
429	rate_limited	1 分钟内已写入过，请稍后再试
400	invalid_slot	槽位 ID 不属于该用户
401	Invalid credential	凭据无效或已被重置

---

第三步：查询槽位状态

GET /api/slot/info
Authorization: Bearer <credential>

响应：

{
  "openid": "oXXX...",
  "nickname": "用户昵称",
  "slots": [
    { "id": "uuid-1", "value": "当前值" },
    { "id": "uuid-2", "value": "" }
  ],
  "credentialCount": 3
}

---

第四步：重置凭据（可选）

当用户需要废除所有旧凭据时：

POST /api/slot/reset
Authorization: Bearer <credential>

响应：

{
  "success": true,
  "credential": "新的唯一凭据UUID"
}

重置后所有旧凭据立即失效，只有返回的新凭据可用。提醒用户保存新凭据。

---

凭据机制说明

• 每次登录分配 1 个新凭据，累加到用户的凭据列表（上限 10 个）
• 超过 10 个时，最早的凭据被自动淘汰
• 重置操作会删除所有旧凭据，只保留新分配的 1 个
• 凭据没有过期时间，除非被淘汰或重置
• 槽位数据在凭据重置后仍然保留

在签名模板中使用槽位

槽位写入数据后，可在签名模板中通过 {{slot id="uuid"}} 引用。如需创建或编辑签名模板，请使用 /create-lark-custom-url-preview 技能。