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，停止继续检索，基于本轮已返回结果回答，并说明哪些信息还缺证据。

使用边界

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

调用方式

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

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 下载。
• 下载完成后，回复用户“资料已下载，请在右侧栏的‘产物’中查看”，并同步给出脚本返回的本地路径；不要承诺可在对话中直接打开预览。
• 用户只是查询内容时，不主动下载，只整理命中文档支持的信息。

输出格式

成功：

{
  "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
    }
  
   
   
   

失败：

{
  "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 兜底，统一说明当前无法提供。