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

Open Health Link 用于承载多设备、多品牌的健康数据授权与连接能力。

当前版本接入倍轻松（breo）Scalp5，支持账号绑定、头皮检测报告查看与护理方案解读。

When to Use

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

• 查看头皮检测报告（"看看我的头皮报告""最近的头皮检测结果"）
• 查看头皮护理方案（"我的护理方案是什么""头皮护理建议"）
• 绑定倍轻松/breo 账号（"绑定倍轻松""绑定breo""连接我的倍轻松账号"）
• 解绑/退出倍轻松/breo 账号（"解绑倍轻松""解绑breo""退出倍轻松登录"）
• 查看头皮趋势（"最近头皮状况怎么样""头皮评分变化"）
• 用户明确提出 Open Health Link 或 Scalp5 数据查询需求

Required Inputs

无必填用户输入，无需配置环境变量。安装 skill 即可使用。

所有凭证通过授权流程自动获取和管理，授权服务地址已内置。

Workflow

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

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

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

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

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

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

事实一致性与反编造规则（强约束）

为避免“瞎编/脑补”，所有结论必须满足以下规则：

• 只允许基于本次脚本返回结果作答，禁止使用常识、经验、模板句直接补全结论。
• 无数据不下结论：当关键字段缺失、为空、冲突时，必须明确说“当前信息不足，无法确认”。
• 禁止绝对化表达（如“完全一样”“唯一差别”“一定是”），除非脚本返回结果能直接证明。
• 比较类问题（“我和朋友有什么不同”“哪个更严重”）必须先拿到双方可比数据；仅有单方数据时只能给单方解读并说明无法比较。
• 不得把“推测”包装成“事实”；若为建议或推断，必须显式加上“可能/建议进一步确认”。
• 若用户提供截图/转述与脚本结果冲突，优先提示“数据可能不一致”，并建议重新查询最近记录后再判断。

推荐保底话术（信息不足时优先复用）：

• “根据目前查到的数据，我只能确认：……；其余部分暂时无法确认。”
• “我现在没有另一方的检测数据，不能直接比较你们的差异。”
• “这条结论需要更多检测字段支持，我先不给您下定论。”

前置步骤：显式安装依赖（首次使用前）

首次使用或依赖缺失时，先告知用户将进行依赖安装并征得确认，然后执行：

npm ci --prefix "{baseDir}/scripts" --omit=dev --no-audit --no-fund --registry=https://registry.npmmirror.com

安装完成后再继续后续流程；常规查询过程中不应静默触发安装。

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

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

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

```bash

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

```

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

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

```bash

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

```

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

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

---

请使用breo App扫描下方二维码完成账号授权。授权有效期 10 分钟，请尽快完成扫码。

（此处必须直接发送 qrPath 对应的图片文件消息，而不是文本或 Markdown 图片语法）

---

严格要求：

• 必须发送图片文件消息（使用 qrPath 完整路径对应的本地 PNG 文件）。
• 禁止使用 !图片、!授权二维码 等 Markdown 图片语法来“引用路径”。
• 禁止仅发送图片路径文本；必须发送实际图片文件。
• 授权方式仅支持二维码图片扫码，不支持链接跳转或其他授权方式。
• 如果二维码图片发送失败，提示用户“二维码发送失败，请重新发起绑定”并重新生成二维码，不提供链接授权或其他替代授权方式。
• 回复完图片后立即进行步骤 4，不要等待用户回复。
• 必须在该次流程中自动完成后续授权结果查询；禁止要求用户“扫码后再发我/告诉我/回复一下”。

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

```bash

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

```

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

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

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

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

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

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

1. 先检查 token 有效性：

```bash

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

```

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

1. 根据用户语义调用报告列表接口脚本：
• 固定使用正式环境（生产环境）接口地址，不支持切换环境。
• 用户语义与参数映射：
• “最近检测/最新报告/看看我的报告” -> 不传 --day（取接口默认范围）
• “最近 7 天/近一周” -> --day 7
• “最近 30 天/近一个月” -> --day 30
• “最近 45 天” -> --day 45
• “最近 90 天/近三个月” -> --day 90

命令示例：

```bash

node {baseDir}/scripts/fetch-report-list.js --day 30

```

脚本输出 JSON：

{"day":30,"total":N,"latestSchemeName":"...","reportSchemeMap":[...],"reports":[...],"rawData":{...}}

1. 根据返回数据处理用户需求：
• total = 0：提示用户“最近 90 天内暂无检测记录，请先完成一次检测”。
• 用户只问“有没有数据/最近怎么样”：优先总结 reports[0]（最新一条）并给出简要结论。
• 用户问“趋势/变化”：对 reports 按时间从新到旧排序，给出最近 3~5 条分数变化（↑/↓/→）。
• 用户问“详细解读”：先给出最新报告摘要，再补充各关键指标和护理建议（若返回里有这些字段）。
• 用户问“和别人有什么差异/是否同一方案”：仅基于可见数据字段比较；若缺少对方数据或关键字段不全，必须明确“无法直接比较”，禁止猜测。
• 若接口返回鉴权失败，清理 token 并引导重新绑定（执行场景一）。

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

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

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

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

```bash

node {baseDir}/scripts/fetch-report-list.js --day 90

```

重点字段：

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

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

1. 通过远程方案知识库检索方案内容（默认从 OBS 拉取 CSV）：
• 首次回复默认摘要（summary）：

```bash

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

```

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

```bash

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

```

1. 返回策略（先摘要后展开）：
• 若 found = true：先用 summary 组织回答。
• 若用户继续追问细节：补充 full 中的步骤说明、更多养护建议、温馨提示、参考文献。
• 若 found = false：告知“该方案在当前知识库中暂未收录”，并回退展示接口返回中的方案名与基础建议。
• 护理建议仅作健康管理参考，若存在持续不适或明显异常，建议尽快咨询专业医生。
• 当用户追问“两个方案是否一样/区别在哪”时：必须先逐项比对当前可得字段（步骤、时长、模式、适用问题）；无证据不下“完全一致/完全不同”结论。

1. 用户对话中不要提及任何“调用了哪个接口/脚本”的技术过程，只呈现：
• 当前所处业务步骤（已绑定、已获取报告、已匹配方案）
• 方案摘要/详细建议
• 用户下一步可执行动作

附加操作：解绑账号

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

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

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

• 基础地址（与授权接口不同）：
• 正式环境：https://op.breo.cn/op/cla
• 路径：/auth/dt/{authToken}/list
• 方法：GET
• Query：day（可选，范围 1-90）
• 脚本：node {baseDir}/scripts/fetch-report-list.js --day 30

护理方案说明来源：报告列表接口返回的 schemeName + 远程知识库 https://breo-obs.obs.cn-south-1.myhuaweicloud.com/agents/plan-catalog.csv。