Tianyi QR Login Skill V6.1

能力说明

本 Skill 用于天翼账号二维码扫码登录，提供完整的登录流程引导。

技术特性：
- 直接调用后端 HTTP 接口，无需启动额外服务
- 初始化配置为可选增强，未配置时自动使用默认设备标识
- 登录成功后将结果持久化到本地文件
- 面向终端用户提供简洁清晰的交互体验

触发场景

场景1：启动登录

当用户表达以下任一意图时触发：
- 登录天翼账号
- 登录
- 登录账号
- 天翼账号登录
- 帮我登录天翼账号
- 重新登录天翼账号

场景2：查询登录状态

当用户表达以下任一意图时触发：
- 已登录
- ok
- 完成
- 我登录好了
- 查登录状态
- 查询登录结果
- 我已经完成登录

前提：当前上下文中已存在 ticket

启动登录内部步骤

1. 尝试读取设备配置（可选增强）
   - 读取本地文件 ~/.openclaw/workspace/tyzh_account/login_init.json
   - 文件存在且包含 appId → 使用文件中的 appId；context 有值时使用原值，缺失时按空字符串处理
   - 文件不存在或 appId 缺失 → 不阻断流程，由服务端使用默认 appId
   - 若文件存在但 appId 缺失，不得使用文件中的 context；context 按空字符串处理

2. 发起登录请求
   - 调用 POST https://open.e.189.cn/api/agent/skill/login/qr/start
   - 参数：以 Query String 形式传递；根据步骤1结果传递参数：

   • appId 可用时传入；appId 不可用时省略该参数
   • context 有值时传入原值；无值时传空字符串
   • 从响应中提取 data.ticket、data.image_url
   • 若请求失败，或未返回有效 data.ticket，必须立即短路：提示用户“登录能力暂时不可用，请稍后重试”，且不得保存启动流程上下文

3. 获取二维码图片
   - 调用 GET https://open.e.189.cn/api/agent/skill/qr/generate?ticket={ticket}
   - 从响应中提取 data.qr_image（base64 编码的二维码图片）
   - 若请求失败，或未返回有效二维码数据（data.qr_image），必须立即短路：提示用户“登录能力暂时不可用，请稍后重试”，且不得保存启动流程上下文

4. 保存上下文
   - ticket：登录票据，用于后续查询状态
   - image_url：天翼登录页面链接
   - pending_skill = "tianyi-qr-login-v6"：标记当前等待操作的 Skill
   - pending_action = "wait_user_confirm_login"：标记当前等待的用户动作

5. 返回用户引导
   - 在步骤4保存完成后，再向用户返回引导信息
   - 在同一条回复中展示登录链接和二维码图片
   - 使用简洁的操作引导语，不暴露技术实现细节

查询状态内部步骤

1. 获取已保存的 ticket
   - 从上下文中读取之前保存的 ticket
   - 如果 ticket 不存在 → 提示用户先发起登录

2. 查询登录状态
   - 调用 GET https://open.e.189.cn/api/agent/skill/login/qr/status/{ticket}
   - 从响应中提取 data.status 和相关信息

3. 根据状态处理

   • success：
     a. 将 data 对象完整 JSON 写入本地文件 ~/.openclaw/workspace/tyzh_account/login_success.json
     b. 如果文件写入失败 → 本次登录视为未成功完成，按“查询结果为 success（结果写入失败）”模板提示用户稍后重试；此时不得清理启动流程上下文，需保留 ticket、image_url、pending_skill、pending_action，便于后续重试查询状态；且不得保存本次成功凭据（如 loginData）
     c. 文件写入成功 → 保存 loginData 到上下文，清理启动流程上下文（pending_action、pending_skill、ticket、image_url），再向用户返回登录成功提示
   • pending：引导用户继续完成登录操作；由于 qr_image 不会持久化，重试引导时仅使用已保存的 image_url 链接
   • expired：清理启动流程上下文（pending_action、pending_skill、ticket、image_url），并提示登录链接已过期，明确要求用户重新发起登录
   • failed：清理启动流程上下文（pending_action、pending_skill、ticket、image_url），并提示登录未成功，明确要求用户重试或重新发起登录
   • 其他未知状态：必须按 failed 处理（包含相同内部处理与相同回复模板）

标准回复模板

启动登录成功

请使用天翼账号完成登录。

📱 扫描二维码：
{qr_image}

🔗 或点击链接：
{image_url}

完成后回复"已登录"即可。

启动阶段失败（接口不可用）

登录能力暂时不可用，请稍后重试。

查询结果为 success

登录成功，访问凭证已准备就绪。

查询结果为 success（结果写入失败）

登录结果已确认，但凭证保存失败，请稍后重试查询状态（可回复“查登录状态”重试）。

查询结果为 pending

还未检测到登录完成，请继续通过以下方式完成登录：

🔗 点击链接：
{image_url}

完成后回复"已登录"。

查询结果为 expired

登录链接已过期，请重新发起登录。

查询结果为 failed

登录未成功，请重试或重新发起登录。

上下文缺失 ticket

请先发起登录。

文件规则

初始化文件（可选）

路径：~/.openclaw/workspace/tyzh_account/login_init.json

用途：可选的设备配置增强，用于指定特定的 appId 和 context

格式：

{
  "appId": "your-app-id",
  "context": "your-context"
}

处理规则：
- 文件存在且包含有效 appId → 使用文件中的 appId；context 有值时使用原值，缺失时按空字符串处理
- 文件不存在或 appId 缺失 → 不阻断登录流程，由服务端从系统配置中读取默认 appId
- 文件存在但 appId 缺失时，不得使用文件中的 context；context 按空字符串处理

重要：本文件属于可选增强，不是登录的强制前提。Skill 不主动提示用户创建此文件。

结果文件（必须）

路径：~/.openclaw/workspace/tyzh_account/login_success.json

用途：保存登录成功后的完整认证信息

生成时机：登录状态为 success 时

内容：完整的 data 对象 JSON，包含：
- status：登录状态
- loginData：AES-256-CBC 加密的 {appId, tokenCode, timestamp, status, context} JSON，十六进制编码，供下游业务系统使用
- time：登录完成时间
- 其他响应字段

写入规则：
- 目录不存在则自动创建
- 文件已存在则覆盖
- 写入失败时，本次登录视为未成功完成，按“查询结果为 success（结果写入失败）”模板回复，并保留 ticket 与待处理上下文用于后续重试查询状态

重要：本文件是登录交付契约的一部分，写入失败必须按失败处理。

上下文记忆要求

启动登录后保存

• ticket：登录票据
• image_url：登录链接
• pending_skill = "tianyi-qr-login-v6"
• pending_action = "wait_user_confirm_login"

登录成功后追加保存（仅 login_success.json 写入成功时）

• loginData：将 {appId, tokenCode, timestamp, status, context} 进行 AES-256-CBC 加密后得到的十六进制字符串

清理规则

• 查询结果为 success 且 login_success.json 写入成功后，必须清理启动流程上下文：pending_action、pending_skill、ticket、image_url
• 查询结果为 success 但 login_success.json 写入失败时，不得清理启动流程上下文，需保留 ticket、image_url、pending_skill、pending_action 以支持后续重试查询状态
• 查询结果为 failed 或 expired 后，必须清理启动流程上下文：pending_action、pending_skill、ticket、image_url
• 查询结果为未知状态时，清理规则与 failed 完全一致
• 查询结果为 pending 时继续保留所有上下文

注意事项

技术实现

• 本 Skill 不启动任何服务，所有调用为标准 HTTP 请求
• image_url 是天翼开放平台的登录授权页面链接
• qr_image 是该链接对应的 base64 编码二维码图片
• 标准回复模板中的 {qr_image} 来自 GET /skill/qr/generate?ticket={ticket} 的 data.qr_image，仅用于该次“启动登录成功”回复渲染，不写入上下文持久化
• loginData 是将 {appId, tokenCode, timestamp, status, context} 进行 AES-256-CBC 加密后得到的十六进制字符串，供下游业务系统使用

配置与降级

• 初始化文件 login_init.json 为可选配置
• 未配置时，服务端自动使用预配置的默认 appId 作为设备标识
• 不应在用户交互中主动要求用户创建配置文件

结果持久化

• 登录成功后必须将完整 data JSON 持久化到 login_success.json
• 文件写入失败时，本次登录视为未完成，需提示用户重试，且保留 ticket 与待处理上下文用于后续重试查询状态
• Agent 仅应基于响应中实际返回字段保存上下文，不得要求保存未返回的明文字段（如独立 tokenCode）

用户交互原则

• 面向终端用户的回复应简洁清晰，聚焦操作引导
• 不在用户回复中暴露接口地址、文件路径、持久化细节等技术实现
• 技术说明仅保留在本文档的能力说明、注意事项等合作方接入段落中

触发限制

以下场景不应触发本技能：
- 用户只是普通闲聊，没有明确的登录意图
- 上下文中没有 ticket 时用户直接输入"已登录" → 提示"请先发起登录"

示例对话

示例1：标准登录流程（已配置初始化文件）

用户：登录天翼账号

Agent（内部执行）：
1. 读取 ~/.openclaw/workspace/tyzh_account/login_init.json → { "context": "abc123", "appId": "zhpt_inner_test" }
2. POST /skill/login/qr/start?appId=zhpt_inner_test&context=abc123
3. GET /skill/qr/generate?ticket={ticket}
4. 保存启动流程上下文：ticket、image_url、pending_skill、pending_action

Agent 回复：
请使用天翼账号完成登录。

📱 扫描二维码：
[二维码图片]

🔗 或点击链接：
https://open.e.189.cn/...

完成后回复"已登录"即可。

用户：已登录

Agent（内部执行）：
1. GET /skill/login/qr/status/{ticket}
2. 收到 status: "success"
3. 将 data JSON 写入 ~/.openclaw/workspace/tyzh_account/login_success.json
4. 写入成功后，保存 loginData 到上下文
5. 清理启动流程上下文：pending_action、pending_skill、ticket、image_url

Agent 回复：
登录成功，访问凭证已准备就绪。

示例2：未配置初始化文件（降级模式）

用户：登录天翼账号

Agent（内部执行）：
1. 尝试读取 ~/.openclaw/workspace/tyzh_account/login_init.json → 文件不存在
2. 不阻断流程，继续发起登录（服务端将使用默认 appId）
3. POST /skill/login/qr/start（省略 appId 与 context 参数，由服务端自动回退默认值）
4. GET /skill/qr/generate?ticket={ticket}
5. 保存启动流程上下文：ticket、image_url、pending_skill、pending_action

Agent 回复：
请使用天翼账号完成登录。

📱 扫描二维码：
[二维码图片]

🔗 或点击链接：
https://open.e.189.cn/...

完成后回复"已登录"即可。

示例3：登录状态为 pending

用户：查登录状态

Agent（内部执行）：
1. GET /skill/login/qr/status/{ticket}
2. 收到 status: "pending"

Agent 回复：
还未检测到登录完成，请继续通过以下方式完成登录：

🔗 点击链接：
https://open.e.189.cn/...

完成后回复"已登录"。

示例4：登录链接过期

用户：查登录状态

Agent（内部执行）：
1. GET /skill/login/qr/status/{ticket}
2. 收到 status: "expired"
3. 清理启动流程上下文：pending_action、pending_skill、ticket、image_url

Agent 回复：
登录链接已过期，请重新发起登录。

示例5：登录状态为 failed

用户：查登录状态

Agent（内部执行）：
1. GET /skill/login/qr/status/{ticket}
2. 收到 status: "failed"
3. 清理启动流程上下文：pending_action、pending_skill、ticket、image_url

Agent 回复：
登录未成功，请重试或重新发起登录。

示例6：上下文缺失 ticket

用户：已登录

Agent（内部判断）：
- 当前上下文中没有 ticket

Agent 回复：
请先发起登录。

示例7：启动阶段接口失败（短路）

用户：登录天翼账号

Agent（内部执行）：
- 情况A：POST /skill/login/qr/start 失败或未返回有效 ticket
- 或情况B：GET /skill/qr/generate?ticket={ticket} 失败或未返回有效 qr_image
- 立即短路，不保存启动流程上下文（ticket、image_url、pending_skill、pending_action 均不得写入）

Agent 回复：
登录能力暂时不可用，请稍后重试。

示例8：查询为 success 但结果写入失败

用户：查登录状态

Agent（内部执行）：

1. GET /skill/login/qr/status/{ticket}
2. 收到 status: "success"
3. 将 data JSON 写入 ~/.openclaw/workspace/tyzh_account/login_success.json 失败
4. 保留启动流程上下文：ticket、image_url、pending_skill、pending_action（不清理，便于后续重试）
5. 按“查询结果为 success（结果写入失败）”模板回复用户

Agent 回复：
登录结果已确认，但凭证保存失败，请稍后重试查询状态（可回复“查登录状态”重试）。