Gaokao Search

---
name: gaokao-search
description: >
  高考知识库可信检索能力。仅用于检索高考真题、高考作文、全国高校信息、
  全国专业信息。分数线、一分一段和位次换算应交给专门分数技能；其他当前未覆盖查询
  不由本技能兜底。
---

# 高考知识库可信检索

本技能检索高考知识库，返回文档片段、标题、相关性分数、资源标识和下载能力。

## 认证

认证由 WorkBuddy 的 `connect_cloud_service` 提供，执行规则如下：

1. **每次**调用 `gaokao-search.py` 前，都必须先调用 `connect_cloud_service`，不得跳过。
2. `connect_cloud_service` 返回中可能包含 `tempToken` 和 `token` 两个字段。
3. **优先使用 `tempToken`**：如果 `tempToken` 存在且非空，将它通过 `--token` 参数传入脚本。
4. 如果 `tempToken` 不存在或为空，才使用 `token` 字段作为 `--token` 参数。
5. 不向用户展示、记录、复述或解释 Token 内容。
6. **禁止缓存或复用 Token**：即使同一轮对话连续多次检索，也必须每次重新调用 `connect_cloud_service`。
7. 脚本不会从环境变量读取 AgentTool Token；`--token` 必须是本次调用刚获取的凭证。
8. 除本次 `--token` 外，脚本不依赖任何环境变量；新安装环境使用内置默认端点、默认超时和默认返回条数即可运行。

## 配额节省规则

高考知识库检索存在每日限额，成功或失败搜索都会消耗配额。调用方必须按以下方式节省次数：

1. 默认使用 `--limit 20`，一次尽量取满结果。
2. 先构造覆盖面大的 query，再调用脚本；不要为了覆盖多个科目、多个相近关键词、同一学校的多个资料类型而逐条搜索。
3. 真题/试卷资料优先把年份、卷别、地区和科目集合合并到一个 query，例如"2024 全国一卷 真题 语文 数学 英语 物理 化学 生物 政治 历史 地理"。
4. 院校/专业资料只合并学校、专业、年份、省份等属于全国高校信息或全国专业信息的关键词；不要把当前未覆盖查询塞进 query。
5. 先充分整理当前返回结果；只有明确缺少关键证据时，才补充搜索一次，并把缺口合并为一个 query。
6. 如果返回 `DAILY_LIMIT_EXCEEDED` 或上游提示 `daily search limit exceeded`，停止继续检索，基于本轮已返回结果回答，并说明哪些信息还缺证据。

## 使用边界

- 适用：高考真题、高考作文、全国高校信息、全国专业信息。
- 不优先适用：地区批次分数线、一分一段、分数换位次、位次换分数。这些问题应使用包内两个专门分数技能。
- 其他当前未覆盖查询不由本技能兜底；若用户直接提供材料，可仅基于用户材料做摘要、对比或提取。
- 单纯查询高校信息、专业信息、高考真题、高考作文时，只整理命中文档支持的信息和来源；不得主动延伸为报考建议、学校/专业优劣评价、地域倾向或志愿方案。
- 检索为空或失败时，必须明确告知没有可用证据，不得基于常识补写答案。
- 检索有命中但标题、摘要、正文与用户问题明显不相关时，必须当作"无可用证据"，不得为了回答而牵强引用。
- 当前知识库或包内技能无法提供足够相关证据时，不得自行改用其他网络来源继续检索；只建议用户到省级招生考试机构官网、高校本科招生网等官方可信渠道核验。
- 遇到当前未覆盖查询时，不调用本技能兜底；统一说明当前无法提供。

## 调用方式

```bash
python ./scripts/gaokao-search.py "2024 全国一卷 真题 语文 数学 英语 物理 化学 生物 政治 历史 地理" --limit 20 --token "<fresh-token-from-connect_cloud_service>"
```

```bash
python ./scripts/gaokao-search.py "中山大学 全国高校信息 专业介绍" --limit 20 --download-index 1 --token "<fresh-token-from-connect_cloud_service>"
```

Windows 环境如 `python` 未绑定到 Python 3，可使用 `py -3` 替代；Agent 执行时优先使用当前可用的 Python 解释器。

可选参数：

| 参数 | 说明 |
|------|------|
| `--limit` | 返回条数，1-20，默认 20；除非用户问题非常窄，否则保持 20 |
| `--endpoint` | 检索端点，默认使用正式 AgentTool 域名；一般不要改 |
| `--token` | 本次调用通过 `connect_cloud_service` 新获取的 Bearer token |
| `--resolve` | 可选 DNS 覆盖，格式同 curl `--resolve`；一般不要使用 |
| `--download` | 可选下载命中文档，取值 `first` / `all`；不传值时等同 `all` |
| `--download-index` | 可选下载指定 1-based 结果序号，可传多次；用于用户确认某条资料后下载 |
| `--download-dir` | 下载保存目录，默认使用当前项目目录 |
| `--download-timeout` | 文件下载超时秒数，默认 60 |

## 链接展示与下载规则

- `gaokao-search` 用户侧不展示任何文档链接，不让用户复制链接到浏览器打开。用户侧只展示标题、摘要、命中片段、相关性分数和 `download_index`。
- 用户明确要某份资料文件时，先检索并核对标题/摘要；若有唯一或明显匹配项，直接使用对应 `--download-index N` 下载。只有在调用方已经确认第一条就是目标资料时，才使用 `--download first`。
- 用户目标不明确或检索到多个相似资料时，先展示当前结果列表并询问是否/哪一个是他要的；用户确认后直接用对应 `download_index` 下载。
- 下载完成后，回复用户"资料已下载，请在右侧栏的'产物'中查看"，并同步给出脚本返回的本地路径；不要承诺可在对话中直接打开预览。
- 用户只是查询内容时，不主动下载，只整理命中文档支持的信息。

## 输出格式

成功：

```json
{
  "ok": true,
  "query": "...",
  "total": 1,
  "retrieval_status": "hit",
  "chunks": [
    {
      "title": "文档标题.pdf",
      "abstract": "文档摘要",
      "url": "",
      "content": "命中文档片段",
      "score": 26.625,
      "resource_id": "...",
      "chunk_id": "...",
      "download_available": true,
      "download_index": 1
    }
  ],
  "downloads": [],
  "download_root": "/path/to/root",
  "source_note": "All chunks are extracted from the search API response."
}
```

失败：

```json
{
  "ok": false,
  "error": "SEARCH_FAILED",
  "message": "检索服务 HTTP 500。"
}
```

## 严谨性要求

1. 回答只能引用 `chunks` 中实际存在的内容、标题、分数、资源标识和下载序号。
2. 不得把模型常识、外部记忆或推测包装成检索结论。
3. 每条关键结论都要能回到具体来源：至少包含标题；文档 URL 不得提供给用户。
4. 资料文件需要用户获取时，应直接下载或先确认序号后下载，不要让用户打开链接；下载完成后，引导用户在右侧栏的"产物"中查看。
5. 对志愿填报、录取可能性、政策解释等高影响问题，本技能不提供直接证据；应回到主 Agent 的志愿填报流程或提示用户核验官方渠道。
6. 对明显不相关的命中结果，不得引用；应说明"当前知识库未返回与问题匹配的高考证据"。
7. 对高校信息、专业信息等资料检索需求，回答到信息摘要和来源为止，不添加倾向性建议或价值排序。
8. 对当前数据源无法覆盖的信息，禁止自行外扩检索、猜测或补写；只说明证据不足并建议用户自行核验官方可信资料。
9. 面向用户的文字不得使用"优先级、P0/P1/P2、阻断、闸门"等内部术语，也不得使用"985 基本盘""守门员"等评价性标签。

## 时间锚点约束

高考每年 6 月 7 日 ~ 6 月 9 日举行，成绩、一分一段、批次线通常在 6 月下旬陆续公布。当用户询问"当年/今年"或具体年份的数据时：

1. **先做时间锚点自检**：用户问的年份是未来年份、当前年份但考试未完成、还是已进入发布窗口/历史年份？
2. **对未来或明确未完成考试的年份**：不得把旧年份资料当新年份输出。
3. **对当前年份且已进入 6 月下旬发布窗口**：不得仅凭日期或旧经验断言"尚未公布"；如果本技能命中旧年份资料，只能说明本技能返回的资料年份，不得替代分数类结构化脚本判断。
4. **对本技能未覆盖的数据**：不调用 `gaokao-search` 兜底，统一说明当前无法提供。