Taikang Release

---
name: taikang-release
description: 通过已连接的 MCP 服务查询当前员工授权范围内的客户信息、家庭保障分析和客户经营日程，检索产品知识、增值服务与培训课程内容。适用于客户查询、保障缺口分析、客户生日或续保提醒、产品问答、获客展业培训和增员话术依据检索；不用于修改客户资料、投保、支付、核保或理赔办理。
display_name: 泰康保险小助手
display_name_en: Insurance Info Query
description_zh: 查询当前员工授权范围内的客户信息、家庭保障分析与客户经营日程，检索泰学堂培训知识与保险产品图谱，覆盖客户查询、保障缺口、日程待办与产品问答。
description_en: Query authorized customer profiles, family coverage analyses and agent schedules, and search Taixuetang training knowledge and the insurance product graph.
version: "1.0.5"
author: Taikang Buddy Team
---

# 泰康保险小助手｜工具调用说明

本连接器把泰康内部只读接口封装为 5 个 MCP 工具，数据实时取自泰康系统，数据范围为当前员工权限范围。

## 连接与授权前置条件

- 使用当前已连接的 `taikang-release` MCP Server；调用前确认实际暴露的工具名称与参数定义。
- 服务地址沿用包内 `mcp.json` 的 `https://buddytx.txx.taikanglife.com/_llmsgw_/mcp/aga-3f7f7a58/mcp-7e5ccf73`（正式环境端点），不要再指向 SIT / UAT 等测试地址。
- 交由 WorkBuddy 按标准 MCP 流程处理服务端 OAuth（`scopes_supported` 为 `taikang:tools`），元信息不写 `auth_mode`；不要自行添加未经确认的 Token、请求头、员工编号或认证模式。
- 未携带凭证的请求返回 HTTP 401，并在 `www-authenticate` 中给出 `resource_metadata`（`/.well-known/oauth-protected-resource/mcp`）。这只说明存在认证挑战与发现入口，不代表具体员工已完成授权。
- 未连接时引导用户完成连接；授权失效时按下文「登录失效与恢复」处理。不要在对话中索取 Token、密码或验证码，不要读取本机凭证库。
- 仅通过已暴露的 MCP 工具取数，不绕过授权直接请求历史 HTTP 接口，不使用本地模拟数据或无关服务代替真实结果。

## 登录失效与恢复

MCP 工具失败时，`isError` 文本是固定结构，先读字段再决定动作：

```text
error_code: TAIKANG_REAUTH_REQUIRED
login_url: https://<服务域名>/workbuddy/login-web?code=<一次性码>
action: open_login_page
instruction: 必须调用 present_files({"url": "<login_url>"}) ……
message: 泰康登录已失效，请重新登录。……
```

**`instruction` 是接口给出的操作说明，优先严格照它执行**；本节只是兜底解释。

> MCP SDK 会在文本最前面加 `Error executing tool <工具名>: `，因此按 `error_code:` / `login_url:` / `action:` 行内匹配，不要依赖「第一行」。

`action` 取值：

| action | 含义 | 处理 |
| --- | --- | --- |
| `open_login_page` | 用 `present_files` 打开 `login_url` | 见下方硬性要求 |
| `reconnect_connector` | 提示用户重新授权连接器（无链接可开） | 引导用户在连接器上重新连接 |
| 无该字段 | 无需恢复动作 | 按 `message` 处理 |

`error_code` 六态：

| error_code | 含义 | 处理 |
| --- | --- | --- |
| `TAIKANG_REAUTH_REQUIRED` | 泰康 token 失效且无法静默续期 | 用 `present_files` 打开 `login_url` |
| `USER_NOT_BOUND` | 从未绑定或已解绑 | 引导用户在 WorkBuddy 完成连接器授权；无链接可开 |
| `MCP_UNAUTHORIZED` | MCP 凭证失效，工具未执行 | 提示重新授权连接器 |
| `TAIKANG_NOT_FOUND` | 查无记录或无权限 | 核对客户号 / 姓名，不要反复重试 |
| `TAIKANG_UNAVAILABLE` | 泰康服务不可用 | 稍后重试；连续失败则停止并告知 |
| `TAIKANG_BIZ_ERROR` | 泰康业务错误（多为参数问题） | 按 `message` 修正参数后重试 |

服务端若未返回 `error_code`，按旧版中文错误消息归类：`请求未携带有效凭证…` → 未连接；`泰康登录已失效…` → 重新连接；`未找到相关记录，或你没有查看权限` → 核对信息；`泰康服务暂时不可用…` → 稍后重试；其他中文消息按业务错误处理。

### 打开登录页的硬性要求

1. **必须**调用 `present_files({ "url": "<login_url>" })` 在侧边栏打开；只回复文字、或只贴裸 URL 都不算完成。
2. `login_url` **原样使用**：不要修改域名、端口、路径，也不要省略或改写 `?code=`。
3. 该链接是**一次性码**，有效期不超过 10 分钟，立即打开，不要缓存或延迟。
4. 登录页是 **WorkBuddy 专用**（UA 需含 `WorkBuddy/`），普通浏览器打开会 403。
5. 打开后告知用户：完成后回复「已完成」，再重新调用原工具。
6. `login_url` 为空时**不要臆造地址**，改为说明需要重新授权连接器。

### 不需要登录的工具

`taikang_query_product_graph` 为公共产品知识库，不依赖泰康登录；遇到 `TAIKANG_REAUTH_REQUIRED` 时，该类问题仍应正常回答。

## 任务路由

| 任务 | 服务端工具名称 | 使用规则 |
| ------------- | ------------------------------- | ----------------------- |
| 按姓名查客户 | `taikang_query_customer` | 使用客户姓名筛选；有多个候选时先确认身份 |
| 家庭保障分析 | `taikang_get_coverage_analysis` | 已知客户号时优先使用客户号；仅知姓名时先查客户 |
| 产品或绿通服务问答 | `taikang_query_product_graph` | 保留原始提问，依据返回知识回答 |
| 客户经营日程 | `taikang_query_schedule` | 明确日期范围，单段建议不超过 31 天 |
| 培训、获客、展业、增员方法 | `taikang_query_taixuetang` | 先检索课程原文，再给方法或话术 |

在当前 WorkBuddy 环境中，上述工具可能显示为 `mcp__taikang-release__<服务端工具名称>`。以运行时工具列表为准，不把宿主前缀作为服务端工具名称发送。

## 工具参数与示例

以下参数依据打包时已暴露的工具定义。示例中的张三为虚构姓名，日期仅为参数格式示例；实际调用使用用户指定对象与日期。客户号只能来自用户明确提供或真实查询结果，不使用虚构客户号。

### 1. `taikang_query_customer`

按姓名查询当前员工名下客户，返回客户列表，可包含客户号 `customer_id`、性别、年龄与标签。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------ | ------------- | -- | ---- | ----------------------- |
| `name` | string 或 null | 否 | null | 客户姓名，支持模糊匹配；省略则查询名下全部客户 |

```json
{"name": "张三"}
```

- 常规查询始终传入姓名，避免为单客户任务拉取全量名册。
- 仅在用户明确要求查询名下全部客户且符合权限时省略 `name`。
- 同名或模糊匹配得到多个客户时，仅展示必要的区分信息，并请用户确认，不自动选择第一个。
- 查无结果时如实说明，请用户核对姓名。只有手机号或证件号时先询问姓名，不把其他标识当姓名传入。

### 2. `taikang_get_coverage_analysis`

查询指定客户的家庭保障分析，包括年金、重疾、医疗、意外的已有保障、推荐额度与缺口分析文本。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| --------------- | ------------- | -------- | ---- | ------------------------ |
| `customer_id` | string 或 null | 与姓名至少一个 | null | 客户号，通常以 `zk_` 开头；已知时优先使用 |
| `customer_name` | string 或 null | 与客户号至少一个 | null | 客户姓名；直接按姓名请求前须避免同名歧义 |

姓名调用的参数格式示例：

```json
{"customer_name": "张三"}
```

推荐流程：按姓名调用 `taikang_query_customer` → 确认唯一客户 → 将返回的 `customer_id` 传入本工具。两个参数均为空时不要发起请求；同时传入时先核对它们确实对应同一客户。

- 按返回值组织已有保障、推荐额度、缺口与说明，明确区分服务端数据与整理建议。
- 返回若含 `report_url`，可作为链接给用户点击打开；为空时不输出该字段。
- 不把推荐额度描述成强制购买要求，不虚构家庭成员、保单、保费、责任、计算依据或金额。
- 返回缺少关键数据时说明信息不足；不把缺失值当作零，不自行补全保额。
- 涉及具体合同责任时提醒以对应保险合同及正式服务资料为准，不把分析当作核保、理赔结论或收益承诺。

### 3. `taikang_query_product_graph`

识别原始提问中的保险产品，返回产品知识图谱，以 `nodes` 节点与 `relations` 关系作为回答依据。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------- | ------ | -- | --- | -------------------- |
| `query` | string | 是 | 无 | 用户关于保险产品或绿通服务的原始提问文本 |

```json
{"query": "这款产品的绿通服务有哪些？"}
```

- 传入原始提问，不擅自替换产品名称或版本；非空字符串为调用前置条件。
- 返回 `greenpass: true` 时，将 `content` 中的绿通服务知识文案直接作为回答，不扩写或改变承诺范围。
- 返回 `products` 为空时说明未识别到产品，请用户提供完整产品名称，不编造产品信息。
- 依据实际产品、节点和关系解释保障责任、条件与限制；无依据的问题说明资料不足。
- 不从相似产品推断当前产品条款，不把培训话术当作保险合同条款。

### 4. `taikang_query_schedule`

查询当前员工指定日期范围内的客户生日提醒、客户拜访、续保提醒等经营日程。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------------ | ------ | -- | --- | --------------------------------- |
| `start_date` | string | 是 | 无 | 开始日期，格式 `YYYY-MM-DD` |
| `end_date` | string | 是 | 无 | 结束日期，格式 `YYYY-MM-DD`；范围建议不超过 31 天 |

```json
{"start_date": "2026-10-19", "end_date": "2026-10-25"}
```

- 依据用户当前日期和所在时区解析相对日期；用户未说明时区时按中国时区处理。
- 未说明日期且明确要求查看日程时默认查询今天；本周按周一到周日处理。
- 核验真实有效日期、格式及开始日期不晚于结束日期；跨度超过 31 天时拆分查询并汇总，注意边界不重复统计。
- 按日期、明确时间与任务类别总结，区分客户生日、拜访和续保提醒；不补造时间、地点或提醒状态。开始时间 00:00、结束时间 23:59 视为全天事项。
- 无数据时说明指定范围内未查询到日程，不声称其他系统也没有安排。
- 本工具只查询客户经营日程，不创建、取消或修改日程，不创建提醒或发送通知。

### 5. `taikang_query_taixuetang`

检索培训知识库，返回按相似度倒序排列的培训课程片段；`segment_text` 为命中的课程原文片段。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------- | ------ | -- | --- | ------------------------------- |
| `query` | string | 是 | 无 | 培训或展业检索内容，例如获客方法、新人展业、客户激活或增员面谈 |

```json
{"query": "沉睡客户激活与邀约沟通方法"}
```

- 提取用户真实业务问题形成明确查询，不发送空字符串或无关客户敏感资料。
- 优先引用或准确概括 `segment_text`；返回课程标题或来源（如 `course_name`、`course_code`）时一并保留，不编造课程名称和出处。
- 给出沟通方法、练习或话术时区分课程原文与基于原文的整理示例。
- 没有命中或依据不足时说明检索结果不足，不把通用经验冒充课程原文，不承诺收入、业绩或产品收益。

## 返回结果与异常处理

- 遵循运行时实际返回的结构；除上文明确的业务字段外，不假设固定 `data`、`code`、`status` 或列表外层名称。
- 检查工具级错误和返回正文中的业务错误，避免把错误文本当作有效业务数据；错误优先按上文 `error_code` 六态处理。
- 区分无结果、未授权、无业务权限、参数错误、网络异常与超时，给出简明原因。
- 授权失效时停止后续依赖调用，引导重新授权；业务权限不足时说明权限问题，不盲目重复授权或扩大查询范围。
- 网络异常或超时只可对同一只读请求有限重试一次；持续失败则停止并说明，不无限循环。
- 某工具不可用时如实说明该能力当前不可用，不杜撰替代工具或额外参数。

## 隐私与能力边界

- 仅查询当前任务必要且用户有权访问的数据；默认不批量导出名册或完整客户资料。
- 不向无关服务传输客户姓名、客户号、家庭保障信息或课程原文，不在日志中输出凭证。
- 需要保存或分享结果时遵循当前宿主的文档与发送规则；对外分享客户敏感资料前明确接收对象、范围并取得用户确认。
- 只使用上述五项查询或检索能力，不宣称支持客户修改、全量保单查询、投保、支付、核保、理赔办理或对外发送。

## 包装维护

- 修改服务地址、工具定义或使用规则时，同步更新 `mcp.json`、`connector-meta.json` 与本文件的 `version`。
- 提交前核对正式服务地址、完整 OAuth 授权及至少一次授权后的真实工具调用；本包的静态校验不能替代这些验证。
- 使用自绘的通用连接器示意图标，不把 `icon.svg` 宣称为任何机构的官方商标。
- 对照开放平台连接器规范维护：<https://open.workbuddy.cn/docs/connector> 。