zcdsj
/
zcbot
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zcbot/skills/documents/SKILL.md

7.7 KiB
Raw Blame History

name description
documents 查内部材料学科知识库(document_search API,7 个学科:胶凝 / 陶瓷 / 玻璃 / 晶体 / 复合 / 耐火 / 检验检测,21W+ 英文学术论文 Markdown 化,跨语言语义检索)。用户找材料领域文献、特定学科论文、材料性能数据时使用;与 research(OpenAlex 外部库)互补,可并用 / 同时试。

Documents

部署在 https://ai.ctc-zc.com:8100/api 的文档检索 API。后端按 kb_name 分库存储 7 个材料学科库(中文命名:胶凝 / 陶瓷基 / 玻璃基 / 晶体材料 / 复合材料 / 耐火材料 / 检验检测,共 21W+ 文件),文档主体是英文学术论文(Elsevier 期刊为主,DOI 前缀文件名),每个文档带 md_content(整篇 Markdown,LLM 友好)+ 可选的原 PDF 下载。API 后端有跨语言语义检索,中英文 query 都能命中英文文档。本 skill 给四个 helper(list_kb / search / download / health),用 run_python 调用,不要自己 httpx 裸调。

何时用

  • 用户要查材料领域文献(7 个学科:胶凝 / 陶瓷 / 玻璃 / 晶体 / 复合 / 耐火 / 检验检测)
  • 用户要查特定材料性能 / 工艺数据(实验数据 / 表征结果 / 公式 / 表格)
  • 写申报书 / 方案 / 报告需要"国内外现状"段,本库 Markdown 化的论文比 research 拿到的裸 PDF/XML 更直接可用
  • 跟 research 并列:都是文献检索 —— research 走 OpenAlex 元数据 + Sci-Hub PDF,搜全网;documents 是本地预收的材料学科子集,已转 Markdown(LLM 直接读,免 OCR / XML 解析)+ 跨语言语义检索(中文 query 也能命中英文论文)。找材料类文献优先 documents,找其他学科或要 DOI 走 research,两者命中不重叠时可并用

何时不用

  • 用户只问通识(直接答)
  • 用户已经给了具体内部文档路径(直接读,不要二次校验)

准备

from skills.documents.client import list_kb, search, download, health

(import 路径由 run_python 注入的 PYTHONPATH 提供,直接写就行)

API key 走 env DOCUMENT_SEARCH_API_KEY,未设会抛 RuntimeError。base_url 走 env DOCUMENT_SEARCH_URL(默认 https://ai.ctc-zc.com:8100/api)。

四个函数

list_kb() -> list[dict]

列所有有效知识库(分类 1-7)。每条含 id / kb_name / ch_name / kb_info / file_count 等。

kbs = list_kb()
for kb in kbs:
    print(kb["id"], kb["kb_name"], kb["ch_name"], kb["file_count"])

用途:用户没指定库 → 先 list_kb() 看有哪些库(中文名 ch_name 看分类),再选 kb_names / classification_ids 缩窄 search 范围。

search(query, kb_names=None, classification_ids=None, max_documents=6) -> list[dict]

搜文档,返回精简列表,每条带 md_content(整篇 Markdown 文本)。

  • query:搜索词。中英文均可 —— 文档主体是英文学术论文,但 API 后端有跨语言语义检索;复杂技术术语用英文更精准(cement hydration > 水泥水化),日常概念中文 OK
  • kb_names:知识库白名单(从 list_kb() 选);None 走 server 默认(单库 mu_34_1740625285897 胶凝)。多库联查就显式传,如 kb_names=["mu_34_1740625285897", "mu_34_1740625303475"]
  • classification_ids:分类 ID 白名单(1-7,对应 7 个学科库);None 不过滤
  • max_documents:1-20,默认 6

学科库 → kb_name 速查(list_kb() 拿全量,这里只列常用):

学科 kb_name
胶凝材料(水泥 / 混凝土 / 砂浆) mu_34_1740625285897
陶瓷基材料 mu_34_1740625303475
玻璃基材料 mu_34_1740625318986
晶体材料 mu_34_1740625346474
复合材料 mu_34_1740625355308
耐火材料 mu_34_1740625365079
检验检测 mu_34_1740625376621 
# 全库搜(走 server 默认单库:胶凝)
docs = search(query="cement hydration", max_documents=10)
for d in docs:
    print(d["file_name"], d["character_count"])
    # 只看前 300 字判断切题 ——— md_content 整体动辄几十 K(实测命中文档常 50K-200K 字符)
    print((d["md_content"] or "")[:300])

# 跨多个学科库联查(如同时找胶凝 + 陶瓷)
docs = search(
    query="concrete carbonation",
    kb_names=["mu_34_1740625285897", "mu_34_1740625303475"],
    max_documents=6,
)

download(file_name, kb_name, working_dir, preview=False) -> str

下载原始文档(PDF / Word / ...)到 <working_dir>/documents/<safe_file_name>,返回相对路径。已存在跳过下载直接复用。file_name 支持原始文件名(example.pdf)或 Markdown 名(example.md),server 自动回退。

rel = download(
    file_name="材料性能手册.pdf",
    kb_name="mu_34_1740625285897",
    working_dir=r"D:/projects/zcbot/workspace/users/<uid>/<wd>",
)
# rel == "documents/材料性能手册.pdf"

health() -> dict

健康检查,公开端点(无需 API key)。主要给 smoke / 排障用:{"status": "healthy", "service": "document_search_api"}。

标准工作流

  1. (可选)list_kb() —— 用户没指定库 / 不确定分类时看一下有哪些
  2. search(query=..., max_documents=6) —— 中英文均可,专业技术术语优先英文
  3. 看返回:
    • 用 file_name + character_count + md_content[:300] 判断切题
    • 切题 → 直接用 md_content 给 LLM 引用(已结构化 Markdown,不需要再下载原件)
    • 需要看图表 / 表格原貌 / 给用户附件 → download(file_name, kb_name, working_dir) 拿原文档,然后用主 agent 的 read 工具读(zcbot 已内置 PDF/Word 文本抽取)
  4. 写产出:把 md_content 关键段落引到申报书 / 方案里,标注来源文件名

md_content 优先 vs 原件下载

  • 绝大多数场景用 md_content 就够 —— API 已把原文档转成 Markdown,LLM 直接读,无需 OCR 或 PDF 抽取
  • 仅以下场景下载原件:
    • 用户明说"要原文件"(给客户附件 / 存档 / 引用页码)
    • md_content 里图表 / 表格 / 公式信息丢失(Markdown 转换无损不了)
    • 文档过大(character_count > 10 万),想用 PDF reader 跳页抽取局部

错误处理

  • DOCUMENT_SEARCH_API_KEY 未设:RuntimeError(client 启动时立即报,而不是裸 401)
  • 401 / 403 Invalid API key:httpx.HTTPStatusError —— key 错或失效,告诉用户检查 env
  • 404 未找到知识库:kb_names 拼写错或库已下线,改 list_kb() 看当前有效列表
  • 404 文件不存在: xxx:download 时常见,可能 server 侧文件丢失或 file_name 拼写错
  • search 命中 0 条:同义词 / 切换中英文 / 缩短 query / 放宽 classification_ids 再试 2-3 次,还是 0 条就明确告诉用户"本库没覆盖,改走 research 或换关键词",不要凭训练数据脑补文献
  • 网络超时 / server 不可达:httpx.ConnectError / httpx.TimeoutException —— 告诉用户"document_search 暂时连不上",不要重试堆栈刷屏

反模式

  • 用 httpx / requests 裸调 API(走 helper,免得 base_url / auth / 字段名漂移时四处改)
  • search(max_documents=20) 一次拉满后 print 全部 md_content(单条就可能几十 K,20 条直接爆 LLM 上下文)—— 只 print file_name + character_count + md_content[:300],要看全文用 docs[i]['md_content']
  • 看到 md_content 切题还 download 一遍原件(md_content 已是 LLM 友好的 Markdown,大多数引用场景够用)
  • 凭 ch_name("胶凝材料学科知识库")就以为 query 要用中文 —— 文档主体是英文,复杂术语用英文更精准
  • 编造 file_name / kb_name —— 不在 list_kb() / search 返回里就明确告诉用户"未命中",不要瞎传 ID
  • 把 download 返回的相对路径当绝对路径用(它是相对 working_dir 的)
  • 不在合适的 task working_dir 里 download(原文档应该落到 task 目录,不要污染 repo)