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

7.1 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 使用三个 host-side tool:document_list_kb / document_search / document_download,不要自己 httpx 裸调,也不要在 run_python 里读 DOCUMENT_SEARCH_API_KEY。

⚠️ 配置条件:只有宿主后端配置了 DOCUMENT_SEARCH_API_KEY 时,上述 tool 才会出现在可用工具列表里。若没有 document_* tool,降级走 research skill(OpenAlex + Sci-Hub,不受影响,中文 query 先转专业英文术语)/ 用户自己导出文档落 task 目录后用 read 工具读。别让 LLM 误推:research 跟本 skill 不同范式,research 不持 secret,任何模式都能用。

何时用

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

何时不用

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

三个 tool

document_list_kb()

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

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

document_search(query, kb_names=None, classification_ids=None, max_documents=6, content_chars_per_doc=1200)

搜文档,返回精简列表,每条带 截断后的 md_content。默认每篇 1200 字符,需要看更多时调大 content_chars_per_doc,上限 5000。

  • query:搜索词。中英文均可 —— 文档主体是英文学术论文,但 API 后端有跨语言语义检索;复杂技术术语用英文更精准(cement hydration > 水泥水化),日常概念中文 OK
  • kb_names:知识库白名单(从 document_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
  • content_chars_per_doc:每篇返回多少 Markdown 字符,默认 1200,最大 5000;不要一上来拉满

学科库 → kb_name 速查(document_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

document_download(file_name, kb_name, preview=False)

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

标准工作流

  1. (可选)document_list_kb —— 用户没指定库 / 不确定分类时看一下有哪些
  2. document_search(query=..., max_documents=6) —— 中英文均可,专业技术术语优先英文
  3. 看返回:
    • 用 file_name + character_count + md_content 判断切题
    • 切题 → 直接用返回的 Markdown 摘要给 LLM 引用;需要更多上下文时提高 content_chars_per_doc 重搜
    • 需要看图表 / 表格原貌 / 给用户附件 → document_download(file_name, kb_name) 拿原文档,然后用主 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_* tool:DOCUMENT_SEARCH_API_KEY 未在宿主配置,改走降级路径
  • 401 / 403 Invalid API key:httpx.HTTPStatusError —— key 错或失效,告诉用户检查 env
  • 404 未找到知识库:kb_names 拼写错或库已下线,改 document_list_kb 看当前有效列表
  • 404 文件不存在: xxx:document_download 时常见,可能 server 侧文件丢失或 file_name 拼写错
  • search 命中 0 条:同义词 / 切换中英文 / 缩短 query / 放宽 classification_ids 再试 2-3 次,还是 0 条就明确告诉用户"本库没覆盖,改走 research 或换关键词",不要凭训练数据脑补文献
  • 网络超时 / server 不可达:httpx.ConnectError / httpx.TimeoutException —— 告诉用户"document_search 暂时连不上",不要重试堆栈刷屏

反模式

  • 用 httpx / requests 裸调 API(走 host tool,免得 base_url / auth / 字段名漂移时四处改,也避免 key 进入 sandbox)
  • document_search(max_documents=20, content_chars_per_doc=5000) 一次拉满(20 条直接爆 LLM 上下文)—— 先用默认值判断切题,只对少数命中文档加大 content_chars_per_doc
  • 看到 md_content 切题还 download 一遍原件(md_content 已是 LLM 友好的 Markdown,大多数引用场景够用)
  • 凭 ch_name("胶凝材料学科知识库")就以为 query 要用中文 —— 文档主体是英文,复杂术语用英文更精准
  • 编造 file_name / kb_name —— 不在 document_list_kb / document_search 返回里就明确告诉用户"未命中",不要瞎传 ID
  • 把 document_download 返回的相对路径当绝对路径用(它是相对 task_dir 的)
  • 尝试给 document_download 传 working_dir(tool 已绑定当前 task_dir,不要让模型指定路径)