zcbot/skills/documents/SKILL.md

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(queries, kb_names=None, classification_ids=None, max_documents=6, content_chars_per_doc=1200)

搜文档,一次可传多个 query 并发搜,返回精简列表,每条带 截断后的 md_content。

• queries:搜索词列表(1-8 条)。把你这一轮想搜的所有不同 query 一次性传进来(queries=["alkali-activated slag strength", "fly ash cement hydration", ...]),别一个 query 一轮 tool call —— 反复来回每轮重发整段上下文,轮数是 token 体量的线性乘数。中英文均可 —— 文档主体是英文学术论文,但 API 后端有跨语言语义检索;复杂技术术语用英文更精准(cement hydration > 水泥水化),日常概念中文 OK。批内自动去重;别堆一堆只差几个词的近义 query(边际递减),先想清楚一组互不重叠的 query 再批量发
• kb_names:知识库白名单(从 document_list_kb 选,对所有 query 生效);None 走 server 默认(单库 mu_34_1740625285897 胶凝)。多库联查就显式传,如 kb_names=["mu_34_1740625285897", "mu_34_1740625303475"]
• classification_ids:分类 ID 白名单(1-7,对应 7 个学科库,对所有 query 生效);None 不过滤
• max_documents:每个 query 返回几篇,1-20,默认 6(批量多 query 时自动缩量控制总输出)
• content_chars_per_doc:每篇返回多少 Markdown 字符,默认 1200,最大 5000(批量多 query 时自动缩量);不要一上来拉满

学科库 → 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(items)

下载原始文档(PDF / Word / ...)到 <working_dir>/documents/<safe_file_name>,返回各自相对路径。一次可传多个文档并发下载,单条失败不连坐其余。已存在跳过下载直接复用。

• items:文档列表(1-10 条),每条 {file_name, kb_name, preview?},如 items=[{"file_name":"a.pdf","kb_name":"mu_34_1740625285897"}, {"file_name":"b.pdf","kb_name":"mu_34_1740625285897"}]。要下几篇就一次性列进来,别一篇一轮 tool call
• file_name 支持原始文件名(example.pdf)或 Markdown 名(example.md),server 自动回退

标准工作流

1. (可选)document_list_kb —— 用户没指定库 / 不确定分类时看一下有哪些
2. document_search(queries=[...]) —— 先规划好一组互不重叠的 query 一次性批量搜,中英文均可,专业技术术语优先英文
3. 看返回:
   • 用 file_name + character_count + md_content 判断切题
   • 切题 → 直接用返回的 Markdown 摘要给 LLM 引用;需要更多上下文时对少数命中文档提高 content_chars_per_doc 单独重搜
   • 需要看图表 / 表格原貌 / 给用户附件 → document_download(items=[...]) 一次性批量拿原文档,然后用主 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
• 一个 query 一轮 tool call 地反复搜(同一意图换着措辞搜十几遍)—— 这是最烧 token 的反模式:每轮重发整段上下文。改成先列一组去重 query 一次 queries=[...] 批量发;一批结果看完不够再发下一批,而不是一条一条挤
• document_download 一篇一轮 tool call —— 把要下的都列进 items=[...] 一次下完
• 看到 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,items 里只放 file_name / kb_name,不要让模型指定路径)