Open Health Link 健康数据连接助手（当前：breo Scalp5）

Open Health Link 用于承载多设备、多品牌的健康数据授权与连接能力。 当前版本接入倍轻松（breo）Scalp5，支持账号绑定、头皮检测报告查看与护理方案解读。

When to Use

当用户的意图涉及以下任一场景时触发：

• 查看头皮检测报告（"看看我的头皮报告""最近的头皮检测结果"）
• 查看头皮护理方案（"我的护理方案是什么""头皮护理建议"）
• 绑定倍轻松/breo 账号（"绑定倍轻松""绑定breo""连接我的倍轻松账号"）
• 解绑/退出倍轻松/breo 账号（"解绑倍轻松""解绑breo""退出倍轻松登录"）
• 查看头皮趋势（"最近头皮状况怎么样""头皮评分变化"）
• 任何涉及 Scalp5 设备、倍轻松（breo）头皮梳、Open Health Link 的话题

Required Inputs

无必填用户输入，无需配置环境变量。安装 skill 即可使用。 所有凭证通过授权流程自动获取和管理，授权服务地址已内置。

Workflow

根据用户意图分三大场景处理。在执行任何脚本前，必须先确保依赖已安装。

用户可见输出规范（强约束）

以下内容仅可在 skill 内部执行与使用，禁止在用户对话中直接展示：

• 终端命令与脚本名（如 node ...）
• 接口地址、路径、请求参数、请求头、环境地址
• 原始 JSON（脚本 stdout/stderr）、字段名细节（如 authToken、schemeName、reportSchemeMap）
• 技术性报错堆栈与调试信息
• “token” 一词及其变体（如“检查 token”“token 失效”）
• 使用 Markdown 图片语法 ![图片](...) 作为图片发送方式

对用户只输出业务流程与结果：

• 用自然语言描述当前进度（例如“正在获取您的最新检测记录”）
• 用业务化结论描述数据（例如“已找到对应护理方案”）
• 默认给简明步骤与建议，不展示内部调用过程
• 仅在用户明确要求“查看技术细节/原始数据”时，才可在脱敏后提供必要信息
• 授权/查询过程尽量合并回复，避免连续发送多条“内部状态”消息

前置步骤：自动安装依赖（每次会话首次调用时执行一次）

在运行任何 Node.js 脚本之前，先检查依赖是否已安装：

node -e "require.resolve('qrcode')" --paths {baseDir}/scripts/node_modules 2>/dev/null || npm install --prefix {baseDir}/scripts --production --silent

如果 node_modules 已存在则瞬间完成，不存在则自动安装（仅一个依赖包，几秒完成）。 此步骤对用户透明，无需任何提示。

场景一：绑定倍轻松账号（或首次使用时自动触发）

当用户明确要求绑定账号，或首次查看数据时本地无有效 token，执行此流程：

1. 运行 token 检查脚本，确认是否已有有效 token：

   node {baseDir}/scripts/token-manager.js check
   

   • 如果输出 {"valid": true, "uid": "..."}，告知用户"您已绑定倍轻松账号"，然后询问是否要重新绑定或进行其他操作。
   • 如果输出 {"valid": false}，继续下面的授权流程。

2. 运行二维码生成脚本，从后端获取授权码并生成二维码图片：

   node {baseDir}/scripts/generate-qrcode.js
   

   脚本输出 JSON（内部使用，关注字段）：{"qrPath": "...", "code": "...", "expiresAt": "..."}

3. 收到脚本输出后，立即按以下格式直接回复用户（不要补充任何技术过程）：

   ---

   请使用breo App扫描下方二维码完成账号授权。授权有效期 10 分钟，请尽快完成扫码。 （此处必须直接发送 qrPath 对应的图片文件消息，而不是文本或 Markdown 图片语法）

   严格要求：

   • 必须发送图片文件消息（使用 qrPath 完整路径对应的本地 PNG 文件）。
   • 禁止使用 ![图片](...)、![授权二维码](...) 等 Markdown 图片语法来“引用路径”。
   • 禁止仅发送图片路径文本；必须发送实际图片文件。
   • 授权方式仅支持二维码图片扫码，不支持链接跳转或其他授权方式。
   • 如果二维码图片发送失败，提示用户“二维码发送失败，请重新发起绑定”并重新生成二维码，不提供链接授权或其他替代授权方式。
   • 回复完图片后立即进行步骤 4，不要等待用户回复。

4. 二维码图片发送后，立即执行前台轮询并自动保存授权结果：

   node {baseDir}/scripts/poll-auth.js <code> --save
   

   • 该步骤为自动步骤，禁止省略；生成二维码后必须立刻执行，不等待用户再次发消息。
   • 该命令会轮询并在授权成功后自动保存 token。
   • 成功时输出：{"status": "authorized", "authToken": "...", "uid": "...", "authType": ..., "saved": true}
   • 超时时输出：{"status": "timeout"}
   • 授权码过期/不存在时输出：{"status": "expired"}
   • 轮询期间可发送一次等待提示："我正在等待授权完成，完成后会立即为您查询结果。"
   • 轮询结束后必须给用户结果反馈：成功、失败、超时三类都必须反馈，禁止静默结束。
   • 若轮询命令异常退出（stderr 或非 0），统一视为“授权查询失败”，向用户给出失败提示并引导重新发起绑定。

5. 授权成功后告知用户："账号授权成功！现在可以为您查看头皮检测报告和护理方案了。"

6. 如果超时或过期，提示用户："授权已超时（10分钟），请重新发起绑定。确保已在breo App中完成扫码授权。"

7. 如果查询失败，提示用户："授权结果查询失败，请重试绑定流程。如已扫码，请稍候重试。"

8. 场景一用户可见话术白名单（优先复用）：

   • 未授权引导："您当前尚未完成账号授权，请先扫码绑定。"
   • 发码提示："请使用breo App扫描下方二维码完成授权（10分钟内有效）。"
   • 等待提示："我正在等待授权完成，完成后会立即为您查询结果。"
   • 成功提示："账号授权成功！现在为您查询最近的检测数据。"
   • 超时提示："本次授权已超时，请重新扫码授权后再试。"
   • 失败提示："授权结果查询失败，请重试绑定流程。"

场景二：查看头皮检测报告

1. 先检查 token 有效性：

   node {baseDir}/scripts/token-manager.js check
   

   如果 token 无效，自动跳转到场景一的授权流程，完成后再继续。

2. 获取有效 token：

   node {baseDir}/scripts/token-manager.js get
   

   输出：{"valid": true, "authToken": "..."}

3. 根据用户语义调用报告列表接口脚本：

   • 默认使用测试环境（--env test）。
   • 仅当用户明确提到“开发环境/联调环境”时使用 --env dev。
   • 用户语义与参数映射：
     • “最近检测/最新报告/看看我的报告” -> 不传 --day（取接口默认范围）
     • “最近 7 天/近一周” -> --day 7
     • “最近 30 天/近一个月” -> --day 30
     • “最近 45 天” -> --day 45
     • “最近 90 天/近三个月” -> --day 90

   命令示例：

   node {baseDir}/scripts/fetch-report-list.js <authToken> --env test --day 30
   

   脚本输出 JSON： {"env":"test","day":30,"total":N,"latestSchemeName":"...","reportSchemeMap":[...],"reports":[...],"rawData":{...}}

4. 根据返回数据处理用户需求：

   • total = 0：提示用户“最近 90 天内暂无检测记录，请先完成一次检测”。
   • 用户只问“有没有数据/最近怎么样”：优先总结 reports[0]（最新一条）并给出简要结论。
   • 用户问“趋势/变化”：对 reports 按时间从新到旧排序，给出最近 3~5 条分数变化（↑/↓/→）。
   • 用户问“详细解读”：先给出最新报告摘要，再补充各关键指标和护理建议（若返回里有这些字段）。
   • 若接口返回鉴权失败，清理 token 并引导重新绑定（执行场景一）。

5. 按照下方「报告展示格式」呈现数据给用户。

场景三：查看头皮护理方案

1. 同场景二，先检查并获取 token。

2. 通过报告列表接口获取最近检测数据（护理方案名在该接口返回）：

   node {baseDir}/scripts/fetch-report-list.js <authToken> --env test --day 90
   

   重点字段：

   • latestSchemeName：最新可用方案名
   • reportSchemeMap：报告与方案映射
   • reports：原始报告列表（含 schemeName）

3. 确定要讲解的方案名：

   • 用户明确指定了某个方案名：优先使用用户指定值。
   • 用户未指定：默认使用 latestSchemeName。
   • 若无 latestSchemeName 且列表里也无 schemeName：提示用户“当前报告未返回护理方案名，先为您展示最近报告摘要”并回退场景二。

4. 通过本地方案知识库检索方案内容：

   • 首次回复默认摘要（summary）：

   node {baseDir}/scripts/plan-catalog.js "<schemeName>" --view summary
   

   • 用户追问“详细讲讲/完整方案/注意事项/文献依据”时：

   node {baseDir}/scripts/plan-catalog.js "<schemeName>" --view full
   

5. 返回策略（先摘要后展开）：

   • 若 found = true：先用 summary 组织回答。
   • 若用户继续追问细节：补充 full 中的步骤说明、更多养护建议、温馨提示、参考文献。
   • 若 found = false：告知“该方案在本地知识库中暂未收录”，并回退展示接口返回中的方案名与基础建议。

6. 用户对话中不要提及任何“调用了哪个接口/脚本”的技术过程，只呈现：

   • 当前所处业务步骤（已绑定、已获取报告、已匹配方案）
   • 方案摘要/详细建议
   • 用户下一步可执行动作

附加操作：解绑账号

当用户要求解绑或退出倍轻松账号时：

node {baseDir}/scripts/token-manager.js clear

告知用户："已解除倍轻松账号绑定。如需再次使用，请重新绑定。"

Output Format

报告展示格式

当展示头皮检测报告时，使用以下格式：

## 🔬 头皮检测报告

**检测日期**：YYYY-MM-DD HH:mm
**综合评分**：XX / 100

### 各维度指标

| 指标 | 得分 | 状态 |
|------|------|------|
| 头皮油脂 | XX | 正常/偏高/偏低 |
| 头皮敏感度 | XX | 正常/轻度/中度 |
| 毛囊健康 | XX | 良好/一般/需关注 |
| 头皮角质 | XX | 正常/偏厚/偏薄 |
| 头发密度 | XX | 正常/偏少 |

### 检测图像

[展示头皮检测图片]

### 分析建议

[基于报告数据给出的个性化解读]

当有多次报告时，先展示最新报告摘要，然后附上趋势对比：

### 📊 近期趋势（最近 N 次检测）

| 日期 | 综合评分 | 变化 |
|------|----------|------|
| MM-DD | XX | ↑/↓/→ |

护理方案展示格式

## 💆 个性化头皮护理方案

**方案生成日期**：YYYY-MM-DD
**基于检测**：YYYY-MM-DD 的检测报告

### 护理步骤

1. **步骤名称**
   - 频率：每周 X 次
   - 方法：具体操作说明
   - 时长：X 分钟

2. **步骤名称**
   ...

### 推荐产品

- 产品名称 — 使用说明

### 注意事项

- [护理注意事项列表]

Error Handling

Token 相关

• Token 不存在：自动引导用户进入绑定流程（场景一），不要报错。
• Token 失效：当数据接口返回鉴权错误时，清除本地 token，提示"您的倍轻松授权已失效，需要重新扫码授权"，然后执行场景一。

网络与接口

• QR 码生成失败：提示"二维码生成失败，请检查网络连接后重试"。
• 轮询超时（10分钟）：提示用户重新发起绑定，确认已在breo App完成扫码。
• 数据接口调用失败：提示"数据获取失败"并附上错误信息，建议用户稍后重试。
• 接口返回空数据：提示"最近 90 天内暂无检测记录，请使用 Scalp5 设备完成一次头皮检测后再来查看。"
• 报告接口 day 参数非法：提示用户参数范围为 1-90 天，并引导改用常见值（7/30/90）。

通用

• 所有脚本执行失败时，读取 stderr 输出并转为用户友好的提示。
• 不要向用户暴露技术细节（如 token 值、接口地址等）。
• 不要回显脚本命令、原始接口响应、字段级调试信息；统一转换为业务化表达。

Data API Reference

头皮报告列表接口（已接入）：

• 基础地址（与授权接口不同）：
  • 开发环境：http://192.168.112.230/op/cla
  • 测试环境：http://124.71.46.48/op/cla
• 路径：/auth/dt/{authToken}/list
• 方法：GET
• Query：day（可选，范围 1-90）
• 脚本：node {baseDir}/scripts/fetch-report-list.js <authToken> --env test --day 30

护理方案说明来源：报告列表接口返回的 schemeName + 本地知识库 {baseDir}/references/plan-catalog.csv。