尧图网页设计 
最近半年我身边的同学、同行都在折腾 Agent。但看了一圈大多数项目还是停留在“能聊天、能查资料”的阶段真正能跑到科研场景里干活的 Agent 少之又少。问题不是模型不够聪明而是很多人只把大模型当成一个问答接口没有给它配上一套可用于工作的“技能包”。我这次要聊的 scientific-agent-skills就是这么个思路把 AI 科学家在日常科研中最常用的能力拆成一套可以被 Agent 调用、复用、组合的技能集合。这篇文章会从一个具体的“文献综述 Agent”项目出发复盘我实际搭建这套技能包的全过程包括目录结构、工具注册、上下文管理、重试机制这些容易被忽略但真正决定项目能不能落地的细节。适合想从“会写 Agent Demo”进阶到“能开发科研自动化 Agent 应用”的开发者或者至少想弄明白 AI Agent 到底怎么介入科研流程的科研人员。1. “AI 科学家技能包”到底在解决什么问题1.1 从聊天机器人到“能干活”的科学家差了什么先说个我踩过的真实场景。以前我让大模型帮我总结几篇论文它确实能总结而且总结得很漂亮。但当你需要它“找出这三篇论文方法上的差异并输出一份对比表”再往下“根据对比结果写一段讨论用于我的 introduction”它就开始暴露问题要么漏掉文献中的关键数据要么自己脑补一个根本不存在的实验条件。更麻烦的是这时候你纠正它它认错态度很好但下一次跑仍然犯同样的错。原因在于聊天模型本质上是“对话式推理”没有任务闭环的概念。它不知道一篇论文的 PDF 存在哪里不知道 Python 环境里能不能跑回归分析也不知道图表生成完该存到哪个目录。技能包要解决的就是这句话让 AI 从“能聊”变成“能干活”。具体地说一个科研 Agent 要干活至少需要四样东西。第一是工具比如检索文献的 API、解析 PDF 的库、执行代码的沙箱第二是流程比如“先检索→再筛选→后精读→最后总结”这样一个固定套路第三是记忆也就是这次任务里已经读过哪些论文、已经生成过哪些结论不能每次都重来第四是验证也就是检查跑出来的结果是否合理。技能包本质上就是把这四样东西封装成一个个可复用的能力块让 Agent 按需加载。我见过不少团队的 Agent 项目Demo 阶段一切顺利一进到真实数据就崩。崩的原因也很集中没有技能包这种工程化设计。他们往往把所有指令写进一个巨大的 system prompt工具调用逻辑散落在业务代码里任务链路稍微拉长上下文就乱成一锅粥。你问它上一轮筛选出了哪 12 篇文献它自己都说不清楚因为那个信息还留在某一个已经丢失的工具返回结果里。技能包的思路恰恰相反它不是“让模型记住一切”而是把一个复杂的科研任务拆成若干个原子技能每个技能负责一段明确的逻辑模型只需要决定“现在调哪个技能”而不是自己从头到尾硬算。1.2 Skill 和 Agent 的区别为什么不能把提示词直接塞给模型现在热搜里天天有人提 Agent、Skill、Harness但真正能说清关系的人不多我最初也踩过概念混淆的坑。Skill 是一个原子能力单元比如“从 PDF 中提取图表”“调用 Scopus API 搜索文献”“根据结构化数据生成论文图表”每个 Skill 都包含对这个能力的描述、输入输出的格式约定、以及一段实际执行的代码或 API 调用逻辑。Agent 则是一个拥有“大局观”的执行主体它负责理解用户目标然后把目标拆解成一系列步骤再按步骤调用不同的 Skill。而 Harness 是更上层的执行框架它是 Agent 运行时的容器管理上下文、工具调度、重试机制和状态持久化。Skill 和 Agent 的关系你可以理解成“工具箱”和“工匠”的关系。工匠收到一个任务先观察需求然后决定先拿锤子还是先拿螺丝刀这些工具本身不会做决定。很多人做 Agent 失败就是把“工匠”和“工具箱”混在一起了。他们试图在一个 Prompt 里既描述工具用法、又描述任务目标、还要求模型自行规划结果模型既没做好规划工具调用也频繁出错。真正稳定的做法是由 Agent 框架负责规划由 Skill 层负责稳定地执行每一步职责边界清晰调试时也能快速定位是谁出了问题。顺便提一下 Harness。如果你看过某些 AI 编程框架会发现它们在编排层用了 Harness 这样的概念。Harness 和 Skill 的区别在于Skill 关注“一件事怎么做”Harness 关注“整个执行环境怎么管理”。Harness 需要处理模型在一次任务中调用工具后的长周期记忆包括哪次调用返回了错误、哪段检索结果已经压缩过、当前 token 预算还剩多少。打个比方Skill 是菜谱上的某一道菜的做法Harness 是整个厨房的排程系统。项目初期可以不管 Harness但规模一大比如多任务并行或需要暂停恢复没有 Harness 基本跑不动。1.3 这类技能包适合谁用、谁能直接受益从我自己的实践经验来看scientific-agent-skills 这类设计最适合三种人。第一种是科研人员尤其是理工科、生物医学、材料科学这些领域的研究生和青年学者。他们的日常工作大量消耗在文献检索、数据清洗、图表绘制和格式排版上这些工作是“低创造性但高规范性”的恰好是技能包最擅长接管的活。我给一个化学方向的朋友部署过一个小型 Agent从 ACS 和 PubMed 上自动抓取化合物活性数据清洗成统一格式后丢给回归模型做 QSAR 分析。他之前手工做这套流程至少要两整天后来让 Agent 跑一遍只需要半小时而剩下的时间主要是他来核对结果是否合理。第二种是算法工程师和 Agent 应用开发者。他们需要一套可以复用的“科研领域技能库”而不是每次接到需求都从零开始写工具调用逻辑。Skill 的好处是模块化你在项目 A 里写好的文献解析技能稍微调整参数就能在项目 B 里复用积累一段时间后开发一个新科研 Agent 的成本会显著降低。第三种情况更宽泛需要自动化处理研究流程的人。比如科技情报分析、研发管理这类角色经常需要周期性产出领域动态报告。过去要人肉盯文献、手动摘录现在用带技能包的 Agent 可以定时抓取、自动摘要、生成分析简报。实际上最近一年出现的不少“AI 科学家”产品核心卖点也不是模型有多聪明而是他们把科学家的日常流程拆成了足够细的技能包再用 Agent 编排执行。理解了这一层你就能明白为什么同样一个模型别人能跑出科研闭环你只能玩出聊天机器人。2. 技能包的整体架构与关键模块拆解2.1 技能描述、参数槽位与依赖声明技能包的最小单元长什么样开始动手前先把技能包的最小单元搞清楚。一个科研场景下的真实技能通常由三部分组成描述文件、执行代码、依赖声明。描述文件里写这个技能是干什么的、适合什么场景、需要哪些输入参数、会返回什么结构的数据。我用 YAML 写过不少技能描述简化版本大概长这样name: literature_search description: 根据关键词在指定数据库中检索学术文献并返回结构化结果。 适合用于系统综述、文献调研、引文追踪等场景。 input: query: type: string required: true description: 检索关键词或自然语言问句 database: type: string required: false default: pubmed enum: [pubmed, arxiv, crossref] limit: type: integer required: false default: 10 minimum: 1 maximum: 50 output: type: array items: title: string authors: array year: integer doi: string abstract: string score: number你可别小看这个 YAML 文件它实际上在做三件重要的事。第一它让 Agent 能在“调用前”就明白这个技能适不适合当前任务而不是等代码跑完才发现参数不对。第二它约束了输出结构后续技能链上的下一步可以直接拿这个结构化结果继续处理不需要再让大模型去“猜测”上一步返回了什么。第三它天然就是一个轻量文档团队协作时别人不用读源码也能搞清楚这个技能怎么用。依赖声明放在单独的文件里常见的有 two 层级。系统级依赖比如你需要在 Linux 环境里装poppler-utils来解析 PDF这是没法靠 pip 解决的。Python 级依赖则简单一些requirements.txt 或 pyproject.toml 都能管理。我的习惯是每一个技能包自带一份requirements.txt并且锁版本。不要图省事不锁版本我在这上面吃亏过不止一次某天重装环境后一个大版本更新的库直接把 PDF 解析结果格式改了Agent 拿到一堆解析失败的文件还浑然不知。锁版本虽然保守但换来的是稳定性这对科研自动化来说值得。2.2 Agent 编排层工具调用与多智能体协作的自然衔接Skill 和 Agent 之间的关系已经有分工了那实际执行中怎么编排我经过多次尝试后觉得科研领域最稳的不是让一个大模型从头到尾一把梭而是“主管 Agent 专业 Agent”的分层模式。主管 Agent 相当于科研团队的组长它接收任务、拆解步骤、验收结果专业 Agent 各自负责某一块深度工作。举一个具体场景你提一个任务“调研 2020 年以来图神经网络在药物发现中的最新进展写一份 1500 字综述”。主管 Agent 先拆解认为需要四类专业能力文献检索、摘要过滤、方法对比、学术写作。如果是一个单体大模型直接生成综述它大概率只能靠训练数据里的陈年记忆来编但分层模式下主管 Agent 会调用文献检索 Agent 去拉真实最近的数据再由摘要过滤 Agent 去重和取舍最后由学术写作 Agent 基于前面真实检索出来的内容生成文字。我在项目里通常给主管 Agent 配置一个“reAct 循环”reAct 就是推理和行动交替进行。模型在每一步先思考“我现在的目标是什么还需要获取什么信息下一步应该调用哪个技能”然后执行一次工具调用看到结果后再进入下一轮思考。这种模式很自然但有个致命问题一旦技能链太长模型很容易原地转圈。比如它反复调用同一个搜索技能每次换了几个关键词组合但始终没有进入下一个阶段。解决办法是在 Agent 的循环里加一个“完成条件检查”。每次工具调用后让模型明确判断当前目标是否已经满足如果满足直接跳出并输出最终结果同时设定最大轮数比如 15 轮超过就直接强制收束。另一种编排方式是 Plan-and-Execute也就是先让模型给自己写一份执行计划再逐步执行。这种方式缺点是灵活度不够如果中途发现计划行不通纠正起来成本很高。我目前用的是混合策略初始几轮用 Plan-and-Execute 让 Agent 给出任务清单后续各步骤之间用 reAct 进行局部微调。这样既有宏观的方向感又不至于在细节里迷路。至于多智能体协作要特别警惕“上下文割裂”问题。每个专业 Agent 之间共享记忆不能只靠自然语言文本传至少要传一份“半结构化摘要”否则信息损耗会非常严重。比如文献检索 Agent 总结完 30 篇文献后传给对比 Agent 的不是完整文本而是一张包含重点方法、数据集、性能指标的半结构化表格对比 Agent 才能拿来进行系统性比较。2.3 记忆系统与状态管理没有记忆的科研 Agent 就是“金鱼”记忆是科研 Agent 里最容易被忽视却又最容易决定成败的一环。科研任务天然是长周期的一次像样的文献调研可能涉及 30 到 50 篇论文阅读和整理过程需要持续几个小时甚至更久。如果 Agent 没有记忆它在第一次通话中找到了 8 篇关键论文结果第二次通话时全忘光了那整个流程就断了。我把 Agent 的记忆拆成三层来管理。第一层是短期工作记忆也就是当前任务线程里的上下文。模型能在一次请求中记住的 token 有限所以这一层通常由 Harness 层管理动态维护当前工具调用结果的摘要。第二层是长期事实记忆跨会话保存。比如项目里维护一份“知识库”每篇精读过的论文都生成一页带向量嵌入的摘要存入向量数据库。当新任务提到“我们之前分析过的那篇用 GAN 做分子生成的论文”Agent 就能通过语义检索快速找到它。第三层是偏好记忆包含用户常设置的参数或者写作风格。比如某一位合作者写论文习惯用“we propose”另一位偏好被动语态这种风格层面的记忆存下来以后Agent 生成的文字就更贴合个人习惯。我建议每个技能在执行前都先检查一下记忆层里有没有可复用的结果避免重复计算。举一个我印象深刻的教训当时跑一个材料筛选任务Agent 连续三次调用了同一篇论文的 PDF 解析接口每一次都把同一个 30 页 PDF 重新解析了一遍浪费了大量时间和 token原因就在于缺少“已解析文档缓存”。后来我在技能层加了一个检查逻辑解析前先在本地看一遍有没有哈希值相同的缓存文件运行成本立刻下降了一大截。状态管理方面核心原则是“所有中间结果必须落盘”不能只留在模型上下文中。每次工具调用返回之后把结果写入一个状态文件比如 JSON Lines 格式的日志这样即使运行中断也能从最后一步恢复而不是从头再来。2.4 验证与容错机制科研 Agent 输出的结论必须先过“质检关”科研 Agent 和普通闲聊 Agent 有一个本质差异科研结论不能“看起来合理”就行它需要可回溯、可复现、可验证。如果 Agent 告诉你说某篇论文里 IC50 是 1.2 微摩尔但你去翻原文发现明明是 12 微摩尔这种错误在科研里是致命的。因此我在技能包里加了专门的验证逻辑每条从外部工具获得的重要数据都要求保留来源索引并在生成结论时标上出处。这一条写得很死宁可不输出结论也不能输出没有来源的信息。数值格式统一是我最早踩坑的环节。不同数据库导出的同一项数据格式五花八门PubMed XML 里的年份可能是2023-07-01Crossref JSON 里则可能是拆分好的date-parts如果你不加标准化就让模型直接读模型很容易把不同格式混在一起生成一个不存在的统计结果。所以每个技能在输出数据前必须做一次“schema 校验和质量检查”主要的检查项包括字段完整性、数值是否在合理区间、日期格式是否统一以及单位是否一致。容错机制则着重解决“工具调用失败后怎么办”的问题。大模型调外部 API 时失败率比你想象的高得多。网络超时算轻的严重的是某些检索接口限流后返回一个伪 200 状态码但 body 里只有一页验证码提示。如果在技能包里预先写好常见的重试与降级策略Agent 的表现会稳定很多。我的做法是在工具调用层统一封装一层“重试包裹器”遇到网络类错误退避重试三次遇到限流类错误等待 30 秒后重试一次如果两次重试后仍失败就不再盲目硬试而是把该障碍标记为一个“跳过项”在最终报告里明确说明“由于数据库限制本项未包含 X 数据库来源”。下表是我在项目里实际用到的验证清单简单但很管用检查项规则失败动作来源完整性每条关键结论必须有 PMID/DOI 或 URL缺失时不进入综述生成阶段数值合理性数量级在领域合理区间内超出范围时打标并要求二次确认日期标准化统一转为 YYYY-MM-DD转换失败时标记 raw 原始值单位一致性统一语种和单位体系不一致时先转换并保留原值引用去重按 DOI 去重重复时合并累计被引次数缓存命中本地已完成任务跳过重跑直接读取缓存结果并写日志3. 从零搭一个“文献综述 Agent”技能包实操复盘3.1 项目初始化与技能目录结构先画好房间再装修纸上谈兵聊了这么多下面直接进入实操。我以“文献综述 Agent”为例带你完整走一遍技能包的搭建流程。先说明环境Python 3.11、LangGraph 作为 Agent 编排框架大模型选用可以通过 API 访问的 Claude 或 GPT 类模型检索工具用 PubMed E-utilities 和 Crossref。下面的目录结构是我实际在用的照抄也能跑起来literature-review-agent/ ├── agent/ │ ├── main.py │ ├── graph.py │ └── prompts.py ├── skills/ │ ├── literature_search/ │ │ ├── description.yaml │ │ ├── requirements.txt │ │ └── main.py │ ├── pdf_parsing/ │ │ ├── description.yaml │ │ ├── requirements.txt │ │ └── main.py │ ├── evidence_extraction/ │ │ ├── description.yaml │ │ ├── requirements.txt │ │ └── main.py │ └── report_writing/ │ ├── description.yaml │ ├── requirements.txt │ └── main.py ├── memory/ │ ├── vector_store.py │ └── checklist.db ├── cache/ │ └── pdf_cache/ ├── outputs/ │ └── reports/ └── configs/ └── settings.yaml这个结构看起来好像有一点“过度工程”实际上每一层都有它的用法。skills 目录下每个文件夹就是一个独立技能内部包含 description.yaml 供 Agent 理解用requirements.txt 锁依赖main.py 是真正的实现。agent 目录放编排层代码graph.py 定义 Agent 的执行图。memory 目录负责向量存储和状态持久化cache 放缓存文件避免重复解析outputs 收 Agent 生成的所有报告。这样做最大的好处是将来新增一个技能只需要在 skills 下加一个文件夹再在 graph.py 里注册一个节点其他代码完全不需要改动可扩展性远超把所有逻辑堆在一个文件里的写法。入口处的 settings.yaml 集中管理 API 密钥、模型名称、温度参数、最大轮数等全局配置。密钥建议不要硬编码在代码里而是放在环境变量或用 dotenv 加载。这样后续在服务器、本地、CI 环境里都能灵活切换不需要改代码。项目初始化时先建虚拟环境再逐次安装目录下各技能的依赖。为了避免依赖冲突我给每个技能维护独立的依赖文件而主环境用最终锁定的全量依赖安装表。3.2 技能注册与工具接入定义“会使用工具”的底层逻辑有了目录骨架接下来做技能注册。这里有个关键的设计思想技能注册表是让 Agent“知道有这些工具存在”的桥梁。我习惯把所有技能的描述动态加载到一个注册表里并定期发给模型作为可选工具列表。代码大概是这样import yaml from pathlib import Path def load_skill_description(skill_name: str) - dict: desc_path Path(fskills/{skill_name}/description.yaml) with open(desc_path, r) as f: return yaml.safe_load(f) def list_available_skills(): skills_dir Path(skills) skill_names [p.name for p in skills_dir.iterdir() if p.is_dir() and (p / main.py).exists()] return {name: load_skill_description(name) for name in skill_names}当你调用某个技能时不能只是返回一个文本告诉模型“我帮你查完了”而是必须把结构化的输出返回给 Agent 框架让框架继续做下一个决策。所以每个技能的 main.py 都有一个约定统一的入口函数。我定的接口很简单每个技能暴露一个run(input_args: dict) - dict函数。这样无论技能内部是调用外部 API、运行 Python 代码还是解析文件对上层 Agent 来说都是统一的“黑盒”。再说工具接入层。以 PubMed 检索为例E-utilities 是公共接口不需要 key 就能用但频率限制很严格每秒最多 3 个请求。严谨的做法是在技能内部加一个请求节流器确保调用频率不会把自己 IP 封掉。下面是我封装的简化版搜索函数里面既有限流也做了缓存import time import requests import xml.etree.ElementTree as ET from diskcache import Cache cache Cache(cache/pubmed_cache) def esearch(query: str, retmax: int 10) - list[str]: if query in cache: return cache[query] url https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi params { db: pubmed, term: query, retmode: json, retmax: retmax, } resp requests.get(url, paramsparams, timeout30) resp.raise_for_status() data resp.json() id_list data[esearchresult].get(idlist, []) cache.set(query, id_list, expire3600 * 24 * 7) time.sleep(0.34) return id_list代码里加了 diskcache 缓存同一个查询关键词在接下来的一周内直接命中不需要再次打扰服务器。这既提速也降低被封风险。拿到 PubMed ID 列表后再调用 efetch 接口拿文章的详细题录做 XML 解析后转成统一 schema 的 JSON。转换过程要注意别把 authors 字段变成一大长串字符串而是拆成结构化数组方便后续做统计分析。比如“最近三年这个方向哪个机构发文最多”这类问题只需要对结构化数组做个 group-by根本不用再让模型去读原文。3.3 跑一次完整任务从自然语言到带引用的综述报告现在进入完整的运行流程。假设我向 Agent 提的需求是“写一篇关于图神经网络在药物发现中应用的简要综述重点涵盖分子表示学习、属性预测和分子生成三个方向引用真实文献总字数 800 字左右”。主管 Agent 的任务规划模块会先识别出四个关键技能并排好执行序列。第一步是“检索筛选”。主管 Agent 把我给出的主题改写成适合数据库的检索式(graph neural network[Title/Abstract]) AND (drug discovery[Title/Abstract]) AND 2020:2025[dp]交给文献检索技能。文献检索技能从 PubMed 和 arXiv 各拉一批候选文献按年份、被引次数、期刊影响力做一个粗过滤最终保留大约 30 篇进入全文解析阶段。这一步看似简单实际上模型需要判断哪些候选和用户关注的三个方向直接相关不是只要标题里含“graph”就算。为了减少误判我在技能里内置了一个“相关性打分”步骤用 embedding 把标题和摘要与用户 query 的比较相似度低于阈值的直接过滤掉。第二步是“精读证据抽取”。30 篇候选文献里有的能拿到 PDF有的只能拿到摘要。能拿到 PDF 的进入全文解析流程用 PyMuPDF 提取文本再切割成 sentence 级片段后用领域专用模型抽取出“模型架构、数据集、基准方法、关键结果”等证据字段。我测试过许多通用大模型直接读长文的效果结论是别让它一次读完整个 PDF否则关键的数值信息很容易丢失。得先把 PDF 切成若干语义块针对每个块分别抽取最后再由大模型汇总去重。这个过程就是典型的 Skill 层级发挥稳定作用的地方。第三步是“结构生成”。Agent 基于抽取出的真实证据按“分子表示学习、属性预测、分子生成”三个段落组织综述。这一步我特意加了一个硬性约束综述中出现的任何一句关键结论后面的引用编号必须来自前面证据抽取阶段得到的真实文献列表。模型不能凭空加引用也不能把 A 论文的结论安到 B 论文头上。为了让控制更稳妥我不会让模型从零写整篇综述而是让它先写一个 outline我检查 outline 里的粒度合适后再逐段生成。每生成一段就回填一次真实引用从源头上消灭幻觉引用。下面这一步的执行日志类似 Agent 实际跑任务时的截图[Plan] 用户目标: 综述图神经网络在药物发现中的进展 [Step 1] 调用技能 literature_search检索式已生成候选: 278 篇 [Step 1] 筛选后保留: 32 篇相关度 0.75 [Step 2] 调用技能 pdf_parsing成功解析 24 篇8 篇仅有摘要 [Step 2] 抽取证据 156 条其中数值型证据 42 条 [Step 3] 调用技能 evidence_extraction检测到 3 篇文献证据不足已标记为“背景性引用” [Step 4] 调用技能 report_writing生成 outline共 3 个 section [Step 4] 分节生成中当前进度: 2/3 [Step 4] 综述生成完成共 824 字引用文献 21 篇 [Verify] 引用完整性校验通过: 每一条结论均有对应 PMID/DOI [Finish] 报告已写入 outputs/reports/gnn_drug_discovery_2025.md实测下来整个流程在普通配置的机器上跑完约 8 分钟成本主要由 PDF 解析和大模型生成构成。如果是让一个研究生手工做同样的事花掉大半天都算正常。当然这个流程并非完美仍有约 15% 比例的文献会因为 PDF 解析质量差或者原文图表信息缺失导致证据抽取不完整。这也是为什么最终报告生成后我还是会快速扫一眼绝对不会盲信。3.4 编排层代码速写用状态机让 Agent 循环可控在编排层我用了 LangGraph 的图结构来定义 Agent 的状态转移。节点就是各个技能边就是它们之间的执行顺序或条件分支。这里简单展示一个核心代码片段说明“图”如何定义技能链接。下面这个例子我简化了实际项目的分支条件会复杂很多比如当检索结果不够时需要跳回重新生成检索词。但核心思想是一样的状态机控制流程技能只负责执行不让模型随机决定下一步调什么工具。from langgraph.graph import StateGraph, END from typing import TypedDict, Optional class AgentState(TypedDict): user_query: str papers: list evidences: list report: Optional[str] step_input: Optional[str] def node_search(state: AgentState) - AgentState: from skills.literature_search.main import run as search_run result search_run({query: state[user_query]}) return {papers: result[papers]} def node_extract(state: AgentState) - AgentState: from skills.evidence_extraction.main import run as extract_run result extract_run({papers: state[papers]}) return {evidences: result[evidences]} def node_write(state: AgentState) - AgentState: from skills.report_writing.main import run as report_run result report_run({ user_query: state[user_query], evidences: state[evidences], }) return {report: result[report]} graph StateGraph(AgentState) graph.add_node(search, node_search) graph.add_node(extract, node_extract) graph.add_node(write, node_write) graph.set_entry_point(search) graph.add_edge(search, extract) graph.add_edge(extract, write) graph.add_edge(write, END) app graph.compile()这样定义出来的状态流有很强约束力。比如你想确保 Agent 不走回头路就可以在图里加一条禁止边某些节点之间不允许跳转你想加一个先并行做两路文献检索再合并结果的分支LangGraph 也提供了对应的条件边语法。相比直接让大模型在循环里自己决定下一步状态机的好处是你一眼就能从图里看出这个 Agent 的整体工作流排查问题时也能直接定位到是哪一个节点出了问题。4. 实战中踩过的坑与排查实录4.1 把技能包做成“一次性用品”上下文爆炸与任务中断恢复这个错误几乎每个从 Demo 走向生产的人都会犯。你可能觉得“既然模型 token 窗口已经有几十万了那就把所有论文全文都塞进去”结果刚开始跑就发现开销暴涨。我接到过的一个项目里导师让 Agent 精读 40 篇论文并生成对比表格。如果直接把每篇论文全文拷进上下文单是输入 token 就要几十万成本高而且大量 token 被浪费在无关的致谢、参考文献列表等区域上。真正有效的阅读策略是分层加工每一步都做信息压缩先全文解析再按段落做语义检索只把跟主线任务相关的句子送入大模型最后再让大模型输出结构化的证据摘要。每一步都会丢一部分次要细节但换来的是上下文可控、结论准确率显著上升。任务中断恢复的问题也很实际。有一次我在本地跑一个长时间文献筛选任务跑到第 20 篇时笔记本因为断电中断了等我重启后重新运行发现 Agent 从第 1 篇开始重新解析起白白耗掉了大半个小时。这是因为我没有做任务级断点。后来我改了代码在每个技能节点执行完后把当前状态已完成步骤、已处理文献 ID 列表、已抽取的证据序列化到一个task_state.json文件里下次启动时先读这个文件如果有未完成步骤就接着跑。这个改动看似不起眼但省下的时间非常可观而且对长周期科研任务来说几乎是必需的。4.2 工具调用不稳定识别“看起来成功实则失败”的垃圾返回大模型在工具调用时最大的坑不是完全调错而是“返回了一个格式很漂亮但暗含幻觉的结果”。比如让 Agent 从论文里抽取实验数据如果论文里确实没有给出数值模型倾向于根据上下文猜一个“看起来合理”的数字填进去而不是老老实实留空。这在一个用 GNN 预测药物毒性的项目里坑过我模型生成的表格里写了一个对照组 p 值实际原文根本未报告该统计量差点导致后续做 meta 分析的分析师误用。从那以后我在所有涉及数据抽取的技能里都强制加一条规则原文里没有的数值必须留 NULL并标注“原文未报告”不允许用估计值补位。另一种垃圾返回是“复读机式成功”。模型调用了某个工具后并没有真的分析工具返回的内容而是根据自己印象直接把结论写出来。判断方法是做一次输出与工具返回的交叉验证。我给事实性技能增加了“引用锚点校验”任何一句重要的结论后面都必须挂上工具返回中的来源 ID如果 Agent 生成的结论在工具返回里找不到对应支撑该句就会被系统自动标红并退回重写。这种强制绑定虽然让生成过程多了一次校验调用但执行结果的可信度提升了好几个等级。4.3 Agent 循环失控与超时重试为什么一直重复“快好了”工具型 Agent 最大的一个稳定运行阻碍是循环失控和运行超时。我自己遇到过“同样技能反复调用 8 次”的严重案例Agent 每次调用领域检索工具后的结果都是没筛选出符合条件的关键论文于是它换一个检索词再来一遍换了 6 个词之后终于想放弃了但又没有“放弃”协议直接卡死。在排查这类现象时我系统性地发现它们频繁出现在“验证 Agent”观察到的上下文正在快速膨胀的阶段尤其在没有给 Agent 设置最大轮数上限的情况下。比如经典的“the agent execution provider did not respond in time”这类超时信息根本原因往往不是 API 服务慢而是 Agent 已经陷入过长的工具链中总超时预算被某一批次大量重试耗尽。解决办法有几个经验值可以参考。第一设全局最大工具调用轮数。文献综述类任务我设 25 轮跑不完也会强制收束不允许无限循环。第二设置单次工具调用的超时时间PubMed 请求我设 30 秒PDF 解析我设 120 秒到点不再等待直接标记失败并走降级逻辑。第三识别“循环模式”如果模型连续三轮调用了同一个技能且检索关键词变化很小系统认定它陷入了无效搜索自动触发“搜索失败”流程把它引导到“更换检索策略”或“精简问题范围”的子技能上而不是继续让它自由发挥。第四对“重复性达到多少轮就截断”这种问题我会把判断写进 Harness 的退出条件里而不是期望模型自觉。4.4 长任务运行token 成本失控与记忆老化科研任务长度通常远超单次调用范围成本控制得从技能链设计阶段就想好。我最早跑一个 15 篇文献的综述任务把每一步的完整中间结果都传给大模型总 token 数轻松超过百万。后来改用“摘要传递”策略每次传递时只保留高信息密度的字段中间产物压缩率常在 10 倍左右token 成本大幅下降。效果变差的情况也有个别细节可能会被裁掉。所以压缩策略要区分关键字段和次要字段比如定量结果、统计显著性这些关键字段不能丢而方法部分的描述性文本可以适度压缩。长任务里的“记忆老化”同样明显。Agent 启动后读过的第 1 篇论文跑到第 30 篇论文时如果被问到“第 1 篇用的什么模型”它可能已经说得不太准确因为早期记忆被后续信息稀释了。可靠的做法不是尽量保留所有旧记忆中而是在需要跨阶段引用时把关键结果写入结构化表并定期 Refresh。每次摘要生成后都将该摘要反向更新到全局记忆库所以即使模型记不清也能查得到。不匹配自然语言模糊检索查询时直接按字段名读取这种“强缓存弱记忆”的模式在长任务场景下表现得更加稳定。4.5 常见问题快速排查清单我日常排查技能包相关问题一般参照下表中的路线从执行环境、技能定义、工具返回三个层次入手。这张表也适合直接贴在项目文档里当团队的故障手册。问题现象可能原因排查方法Agent 完全不调用技能技能描述不清晰模型没识别出可用工具检查 description.yaml 里的场景描述和动词提示调用了技能但参数全错输入槽位定义不具体优化 input 字段的 description并给每个参数附一个示例值检索结果大量重复上下文记忆没联动技能内查询历史在检索技能内维护一个已查关键词集合重复时自动剔除PDF 解析结果乱码扫描版 PDF 需要 OCR分析引擎不会自动识别增加 OCR 预处理步骤或提示用户提供文本版论文本地和容器环境运行结果不一致依赖版本漂移使用锁文件重装环境并在 CI 中构建固定镜像生成报告引用链接仍无效Agent 依靠印象引用而没有严格回填在 report_writing 技能里做一遍引用锚点校验缺失就重写单轮返回超时Agent 内部循环分支过多缩短工具返回内容并压缩上下文或拆分任务再串行执行长任务中途宕机无法恢复缺任务级状态持久化每个技能执行完将状态写入 JSON重启时读取并断点续跑生成了“看似合理”的错误数值模型擅自补全原文缺失数据在抽取技能里强制原文未有数值一律留 NULL除了这张表有一个底层经验想专门说明技能包的目录命名和描述文案真不能随便起。有一次我把一个“从论文中提取实验方法”的技能命名为extract_methoddescription 又写得很含糊结果模型将该技能用于“提取我上一个问题中的所有方法”这种非预期任务导致几条垃圾调用混入流程。后来我把技能名改成extract_experimental_method_from_pdfdescription 写明“从论文 PDF 的 Methods/Experimental 部分抽取实验步骤、仪器型号、试剂用量”调用准确性立刻变好。想让模型用对工具描述里一定要给出足够的情境线索和反例别指望模型能从精炼短句里自己悟出不变量。5. 技能包的复用与进化我的路线图与实践体会5.1 单个 Agent 到技能集市让一套技能包服务多个 Agent 项目现在回头来看scientific-agent-skills 的最大价值不是某一个 Agent 能跑通而在于它沉淀出的技能可以跨项目复用。最初我为一篇论文的文献综述写了一个 PDF 解析技能后来完全不需要改动就拿去给另一个化学组的专利分析项目使用了后一个项目只要把输出 schema 稍微调整一下即可从“提取方法”切换到“提取权利要求要素”。这种复用得益于一开始就把技能做成了“无状态”的独立模块它不关心调用方是谁只负责完成某件具体的事通过输入参数把差异全部暴露出来。长期演进上我建议团队至少维护一个内部的“技能注册中心”用版本号记录每个技能的迭代历史。当某位同事修复了 PubMed 接口限流处理的 bug 并发布 v1.3 后所有引用了该技能的 Agent 都会自动受益。这个思路和前端社区的 npm 包管理逻辑一致。你如果现在刚开始入坑不必急着搭注册中心但至少要给每个技能目录加一个CHANGELOG.md哪怕只是日期加一行说明也能省掉很多“这个技能谁改过、为什么行为变了”的麻烦。5.2 Agent 框架的选型路线从 LangGraph 到自研 Harness 的渐进式思考关于编排框架的选型不少初学者在第一步就陷入“框架选哪个才对”的焦虑。我自己的经验是先别纠缠框架手里没有跑通过一个小 Agent 之前讨论 LangGraph、CrewAI、AutoGen 的优劣没有任何基础。先找一个教程简单、社区活跃、和 Python 生态契合的框架跑通一个最简流程体会一下 tool calling 和状态传递。之后再开始关注更上游的执行容器概念比如 Harness 这类偏自研方向的东西。Harness 通常承载着更多的上下文管理、生命周期控制和安全边界管理逻辑对框架化场景很有价值但如果你连最基本的检索技能都还没稳定过早引入 Harness 只会让排查复杂度翻倍。等规模到了“需要同时管理 5 个以上 Agent 技能链”的时候再考虑进一步抽象 Agent 流程是合理的。到那个阶段你自然会发现哪些流程是通用的哪些是本项目特有的。把通用部分下沉到框架或 Harness 中把特有部分留成普通技能这个“够用再抽象”的过程比一开始就追求大而全的设计要顺滑得多。5.3 最后几条小技巧来自我这大半年被 Agent 反复摩擦的总结第一给 Agent 设置“不自信标记”。如果 Agent 对某一步的把握不足允许它输出一个confidence: low字段然后我在后续人工复核时优先检查这些低置信区间。别要求模型每次都有 100% 的确定感能用机制暴露不确定性正是自动化系统成熟的表现。第二别把所有技能都暴露给模型。每加一个技能模型的工具选择空间就多一个维度选择失误率也会小幅上升。实际跑综述任务时我只在对应阶段暴露对应的两三个技能而不是同时给它 20 个工具。第三测试 Agent 时不要只测成功路径还要专门设计“刁钻输入”测试比如彻底检索不到文献的情况、PDF 是乱码的情况。Agent 能不能体面地处理“没有结果”这件事往往比能不能顺利跑通理想流程更体现工程质量。这个技能包项目刚做好时我以为最高光的时刻会是某次自动化流程全绿跑通、生成了一份漂亮综述。但后来真正让我觉得值回票价的是实验室一位师弟拿着这份技能包改出了一套药物专利对比分析工具他基本没动底层的技能逻辑只换了检索源和输出模板。那一刻我才意识到给 AI 科学家准备“技能”本质上是在帮每一个具体的研究者积累他们自己的“可复用经验”。这种积累不依赖某一个大模型版本的能力而是沉淀在技能包本身里模型换了一代又一代这些技能仍然可以继续为研究者服务。所以如果你也想入坑科研 Agent我建议不要从吹嘘最宏大的“全自动 AI 科学家”开始而是从把身边一项三十分钟以上的重复性研究工作拆成第一个技能包开始。做完这一个你自然就知道下一步该做什么了。 科研Agent技能包实战：从文献综述搭建到自动化流程复盘
最近半年我身边的同学、同行都在折腾 Agent。但看了一圈大多数项目还是停留在“能聊天、能查资料”的阶段真正能跑到科研场景里干活的 Agent 少之又少。问题不是模型不够聪明而是很多人只把大模型当成一个问答接口没有给它配上一套可用于工作的“技能包”。我这次要聊的 scientific-agent-skills就是这么个思路把 AI 科学家在日常科研中最常用的能力拆成一套可以被 Agent 调用、复用、组合的技能集合。这篇文章会从一个具体的“文献综述 Agent”项目出发复盘我实际搭建这套技能包的全过程包括目录结构、工具注册、上下文管理、重试机制这些容易被忽略但真正决定项目能不能落地的细节。适合想从“会写 Agent Demo”进阶到“能开发科研自动化 Agent 应用”的开发者或者至少想弄明白 AI Agent 到底怎么介入科研流程的科研人员。1. “AI 科学家技能包”到底在解决什么问题1.1 从聊天机器人到“能干活”的科学家差了什么先说个我踩过的真实场景。以前我让大模型帮我总结几篇论文它确实能总结而且总结得很漂亮。但当你需要它“找出这三篇论文方法上的差异并输出一份对比表”再往下“根据对比结果写一段讨论用于我的 introduction”它就开始暴露问题要么漏掉文献中的关键数据要么自己脑补一个根本不存在的实验条件。更麻烦的是这时候你纠正它它认错态度很好但下一次跑仍然犯同样的错。原因在于聊天模型本质上是“对话式推理”没有任务闭环的概念。它不知道一篇论文的 PDF 存在哪里不知道 Python 环境里能不能跑回归分析也不知道图表生成完该存到哪个目录。技能包要解决的就是这句话让 AI 从“能聊”变成“能干活”。具体地说一个科研 Agent 要干活至少需要四样东西。第一是工具比如检索文献的 API、解析 PDF 的库、执行代码的沙箱第二是流程比如“先检索→再筛选→后精读→最后总结”这样一个固定套路第三是记忆也就是这次任务里已经读过哪些论文、已经生成过哪些结论不能每次都重来第四是验证也就是检查跑出来的结果是否合理。技能包本质上就是把这四样东西封装成一个个可复用的能力块让 Agent 按需加载。我见过不少团队的 Agent 项目Demo 阶段一切顺利一进到真实数据就崩。崩的原因也很集中没有技能包这种工程化设计。他们往往把所有指令写进一个巨大的 system prompt工具调用逻辑散落在业务代码里任务链路稍微拉长上下文就乱成一锅粥。你问它上一轮筛选出了哪 12 篇文献它自己都说不清楚因为那个信息还留在某一个已经丢失的工具返回结果里。技能包的思路恰恰相反它不是“让模型记住一切”而是把一个复杂的科研任务拆成若干个原子技能每个技能负责一段明确的逻辑模型只需要决定“现在调哪个技能”而不是自己从头到尾硬算。1.2 Skill 和 Agent 的区别为什么不能把提示词直接塞给模型现在热搜里天天有人提 Agent、Skill、Harness但真正能说清关系的人不多我最初也踩过概念混淆的坑。Skill 是一个原子能力单元比如“从 PDF 中提取图表”“调用 Scopus API 搜索文献”“根据结构化数据生成论文图表”每个 Skill 都包含对这个能力的描述、输入输出的格式约定、以及一段实际执行的代码或 API 调用逻辑。Agent 则是一个拥有“大局观”的执行主体它负责理解用户目标然后把目标拆解成一系列步骤再按步骤调用不同的 Skill。而 Harness 是更上层的执行框架它是 Agent 运行时的容器管理上下文、工具调度、重试机制和状态持久化。Skill 和 Agent 的关系你可以理解成“工具箱”和“工匠”的关系。工匠收到一个任务先观察需求然后决定先拿锤子还是先拿螺丝刀这些工具本身不会做决定。很多人做 Agent 失败就是把“工匠”和“工具箱”混在一起了。他们试图在一个 Prompt 里既描述工具用法、又描述任务目标、还要求模型自行规划结果模型既没做好规划工具调用也频繁出错。真正稳定的做法是由 Agent 框架负责规划由 Skill 层负责稳定地执行每一步职责边界清晰调试时也能快速定位是谁出了问题。顺便提一下 Harness。如果你看过某些 AI 编程框架会发现它们在编排层用了 Harness 这样的概念。Harness 和 Skill 的区别在于Skill 关注“一件事怎么做”Harness 关注“整个执行环境怎么管理”。Harness 需要处理模型在一次任务中调用工具后的长周期记忆包括哪次调用返回了错误、哪段检索结果已经压缩过、当前 token 预算还剩多少。打个比方Skill 是菜谱上的某一道菜的做法Harness 是整个厨房的排程系统。项目初期可以不管 Harness但规模一大比如多任务并行或需要暂停恢复没有 Harness 基本跑不动。1.3 这类技能包适合谁用、谁能直接受益从我自己的实践经验来看scientific-agent-skills 这类设计最适合三种人。第一种是科研人员尤其是理工科、生物医学、材料科学这些领域的研究生和青年学者。他们的日常工作大量消耗在文献检索、数据清洗、图表绘制和格式排版上这些工作是“低创造性但高规范性”的恰好是技能包最擅长接管的活。我给一个化学方向的朋友部署过一个小型 Agent从 ACS 和 PubMed 上自动抓取化合物活性数据清洗成统一格式后丢给回归模型做 QSAR 分析。他之前手工做这套流程至少要两整天后来让 Agent 跑一遍只需要半小时而剩下的时间主要是他来核对结果是否合理。第二种是算法工程师和 Agent 应用开发者。他们需要一套可以复用的“科研领域技能库”而不是每次接到需求都从零开始写工具调用逻辑。Skill 的好处是模块化你在项目 A 里写好的文献解析技能稍微调整参数就能在项目 B 里复用积累一段时间后开发一个新科研 Agent 的成本会显著降低。第三种情况更宽泛需要自动化处理研究流程的人。比如科技情报分析、研发管理这类角色经常需要周期性产出领域动态报告。过去要人肉盯文献、手动摘录现在用带技能包的 Agent 可以定时抓取、自动摘要、生成分析简报。实际上最近一年出现的不少“AI 科学家”产品核心卖点也不是模型有多聪明而是他们把科学家的日常流程拆成了足够细的技能包再用 Agent 编排执行。理解了这一层你就能明白为什么同样一个模型别人能跑出科研闭环你只能玩出聊天机器人。2. 技能包的整体架构与关键模块拆解2.1 技能描述、参数槽位与依赖声明技能包的最小单元长什么样开始动手前先把技能包的最小单元搞清楚。一个科研场景下的真实技能通常由三部分组成描述文件、执行代码、依赖声明。描述文件里写这个技能是干什么的、适合什么场景、需要哪些输入参数、会返回什么结构的数据。我用 YAML 写过不少技能描述简化版本大概长这样name: literature_search description: 根据关键词在指定数据库中检索学术文献并返回结构化结果。 适合用于系统综述、文献调研、引文追踪等场景。 input: query: type: string required: true description: 检索关键词或自然语言问句 database: type: string required: false default: pubmed enum: [pubmed, arxiv, crossref] limit: type: integer required: false default: 10 minimum: 1 maximum: 50 output: type: array items: title: string authors: array year: integer doi: string abstract: string score: number你可别小看这个 YAML 文件它实际上在做三件重要的事。第一它让 Agent 能在“调用前”就明白这个技能适不适合当前任务而不是等代码跑完才发现参数不对。第二它约束了输出结构后续技能链上的下一步可以直接拿这个结构化结果继续处理不需要再让大模型去“猜测”上一步返回了什么。第三它天然就是一个轻量文档团队协作时别人不用读源码也能搞清楚这个技能怎么用。依赖声明放在单独的文件里常见的有 two 层级。系统级依赖比如你需要在 Linux 环境里装poppler-utils来解析 PDF这是没法靠 pip 解决的。Python 级依赖则简单一些requirements.txt 或 pyproject.toml 都能管理。我的习惯是每一个技能包自带一份requirements.txt并且锁版本。不要图省事不锁版本我在这上面吃亏过不止一次某天重装环境后一个大版本更新的库直接把 PDF 解析结果格式改了Agent 拿到一堆解析失败的文件还浑然不知。锁版本虽然保守但换来的是稳定性这对科研自动化来说值得。2.2 Agent 编排层工具调用与多智能体协作的自然衔接Skill 和 Agent 之间的关系已经有分工了那实际执行中怎么编排我经过多次尝试后觉得科研领域最稳的不是让一个大模型从头到尾一把梭而是“主管 Agent 专业 Agent”的分层模式。主管 Agent 相当于科研团队的组长它接收任务、拆解步骤、验收结果专业 Agent 各自负责某一块深度工作。举一个具体场景你提一个任务“调研 2020 年以来图神经网络在药物发现中的最新进展写一份 1500 字综述”。主管 Agent 先拆解认为需要四类专业能力文献检索、摘要过滤、方法对比、学术写作。如果是一个单体大模型直接生成综述它大概率只能靠训练数据里的陈年记忆来编但分层模式下主管 Agent 会调用文献检索 Agent 去拉真实最近的数据再由摘要过滤 Agent 去重和取舍最后由学术写作 Agent 基于前面真实检索出来的内容生成文字。我在项目里通常给主管 Agent 配置一个“reAct 循环”reAct 就是推理和行动交替进行。模型在每一步先思考“我现在的目标是什么还需要获取什么信息下一步应该调用哪个技能”然后执行一次工具调用看到结果后再进入下一轮思考。这种模式很自然但有个致命问题一旦技能链太长模型很容易原地转圈。比如它反复调用同一个搜索技能每次换了几个关键词组合但始终没有进入下一个阶段。解决办法是在 Agent 的循环里加一个“完成条件检查”。每次工具调用后让模型明确判断当前目标是否已经满足如果满足直接跳出并输出最终结果同时设定最大轮数比如 15 轮超过就直接强制收束。另一种编排方式是 Plan-and-Execute也就是先让模型给自己写一份执行计划再逐步执行。这种方式缺点是灵活度不够如果中途发现计划行不通纠正起来成本很高。我目前用的是混合策略初始几轮用 Plan-and-Execute 让 Agent 给出任务清单后续各步骤之间用 reAct 进行局部微调。这样既有宏观的方向感又不至于在细节里迷路。至于多智能体协作要特别警惕“上下文割裂”问题。每个专业 Agent 之间共享记忆不能只靠自然语言文本传至少要传一份“半结构化摘要”否则信息损耗会非常严重。比如文献检索 Agent 总结完 30 篇文献后传给对比 Agent 的不是完整文本而是一张包含重点方法、数据集、性能指标的半结构化表格对比 Agent 才能拿来进行系统性比较。2.3 记忆系统与状态管理没有记忆的科研 Agent 就是“金鱼”记忆是科研 Agent 里最容易被忽视却又最容易决定成败的一环。科研任务天然是长周期的一次像样的文献调研可能涉及 30 到 50 篇论文阅读和整理过程需要持续几个小时甚至更久。如果 Agent 没有记忆它在第一次通话中找到了 8 篇关键论文结果第二次通话时全忘光了那整个流程就断了。我把 Agent 的记忆拆成三层来管理。第一层是短期工作记忆也就是当前任务线程里的上下文。模型能在一次请求中记住的 token 有限所以这一层通常由 Harness 层管理动态维护当前工具调用结果的摘要。第二层是长期事实记忆跨会话保存。比如项目里维护一份“知识库”每篇精读过的论文都生成一页带向量嵌入的摘要存入向量数据库。当新任务提到“我们之前分析过的那篇用 GAN 做分子生成的论文”Agent 就能通过语义检索快速找到它。第三层是偏好记忆包含用户常设置的参数或者写作风格。比如某一位合作者写论文习惯用“we propose”另一位偏好被动语态这种风格层面的记忆存下来以后Agent 生成的文字就更贴合个人习惯。我建议每个技能在执行前都先检查一下记忆层里有没有可复用的结果避免重复计算。举一个我印象深刻的教训当时跑一个材料筛选任务Agent 连续三次调用了同一篇论文的 PDF 解析接口每一次都把同一个 30 页 PDF 重新解析了一遍浪费了大量时间和 token原因就在于缺少“已解析文档缓存”。后来我在技能层加了一个检查逻辑解析前先在本地看一遍有没有哈希值相同的缓存文件运行成本立刻下降了一大截。状态管理方面核心原则是“所有中间结果必须落盘”不能只留在模型上下文中。每次工具调用返回之后把结果写入一个状态文件比如 JSON Lines 格式的日志这样即使运行中断也能从最后一步恢复而不是从头再来。2.4 验证与容错机制科研 Agent 输出的结论必须先过“质检关”科研 Agent 和普通闲聊 Agent 有一个本质差异科研结论不能“看起来合理”就行它需要可回溯、可复现、可验证。如果 Agent 告诉你说某篇论文里 IC50 是 1.2 微摩尔但你去翻原文发现明明是 12 微摩尔这种错误在科研里是致命的。因此我在技能包里加了专门的验证逻辑每条从外部工具获得的重要数据都要求保留来源索引并在生成结论时标上出处。这一条写得很死宁可不输出结论也不能输出没有来源的信息。数值格式统一是我最早踩坑的环节。不同数据库导出的同一项数据格式五花八门PubMed XML 里的年份可能是2023-07-01Crossref JSON 里则可能是拆分好的date-parts如果你不加标准化就让模型直接读模型很容易把不同格式混在一起生成一个不存在的统计结果。所以每个技能在输出数据前必须做一次“schema 校验和质量检查”主要的检查项包括字段完整性、数值是否在合理区间、日期格式是否统一以及单位是否一致。容错机制则着重解决“工具调用失败后怎么办”的问题。大模型调外部 API 时失败率比你想象的高得多。网络超时算轻的严重的是某些检索接口限流后返回一个伪 200 状态码但 body 里只有一页验证码提示。如果在技能包里预先写好常见的重试与降级策略Agent 的表现会稳定很多。我的做法是在工具调用层统一封装一层“重试包裹器”遇到网络类错误退避重试三次遇到限流类错误等待 30 秒后重试一次如果两次重试后仍失败就不再盲目硬试而是把该障碍标记为一个“跳过项”在最终报告里明确说明“由于数据库限制本项未包含 X 数据库来源”。下表是我在项目里实际用到的验证清单简单但很管用检查项规则失败动作来源完整性每条关键结论必须有 PMID/DOI 或 URL缺失时不进入综述生成阶段数值合理性数量级在领域合理区间内超出范围时打标并要求二次确认日期标准化统一转为 YYYY-MM-DD转换失败时标记 raw 原始值单位一致性统一语种和单位体系不一致时先转换并保留原值引用去重按 DOI 去重重复时合并累计被引次数缓存命中本地已完成任务跳过重跑直接读取缓存结果并写日志3. 从零搭一个“文献综述 Agent”技能包实操复盘3.1 项目初始化与技能目录结构先画好房间再装修纸上谈兵聊了这么多下面直接进入实操。我以“文献综述 Agent”为例带你完整走一遍技能包的搭建流程。先说明环境Python 3.11、LangGraph 作为 Agent 编排框架大模型选用可以通过 API 访问的 Claude 或 GPT 类模型检索工具用 PubMed E-utilities 和 Crossref。下面的目录结构是我实际在用的照抄也能跑起来literature-review-agent/ ├── agent/ │ ├── main.py │ ├── graph.py │ └── prompts.py ├── skills/ │ ├── literature_search/ │ │ ├── description.yaml │ │ ├── requirements.txt │ │ └── main.py │ ├── pdf_parsing/ │ │ ├── description.yaml │ │ ├── requirements.txt │ │ └── main.py │ ├── evidence_extraction/ │ │ ├── description.yaml │ │ ├── requirements.txt │ │ └── main.py │ └── report_writing/ │ ├── description.yaml │ ├── requirements.txt │ └── main.py ├── memory/ │ ├── vector_store.py │ └── checklist.db ├── cache/ │ └── pdf_cache/ ├── outputs/ │ └── reports/ └── configs/ └── settings.yaml这个结构看起来好像有一点“过度工程”实际上每一层都有它的用法。skills 目录下每个文件夹就是一个独立技能内部包含 description.yaml 供 Agent 理解用requirements.txt 锁依赖main.py 是真正的实现。agent 目录放编排层代码graph.py 定义 Agent 的执行图。memory 目录负责向量存储和状态持久化cache 放缓存文件避免重复解析outputs 收 Agent 生成的所有报告。这样做最大的好处是将来新增一个技能只需要在 skills 下加一个文件夹再在 graph.py 里注册一个节点其他代码完全不需要改动可扩展性远超把所有逻辑堆在一个文件里的写法。入口处的 settings.yaml 集中管理 API 密钥、模型名称、温度参数、最大轮数等全局配置。密钥建议不要硬编码在代码里而是放在环境变量或用 dotenv 加载。这样后续在服务器、本地、CI 环境里都能灵活切换不需要改代码。项目初始化时先建虚拟环境再逐次安装目录下各技能的依赖。为了避免依赖冲突我给每个技能维护独立的依赖文件而主环境用最终锁定的全量依赖安装表。3.2 技能注册与工具接入定义“会使用工具”的底层逻辑有了目录骨架接下来做技能注册。这里有个关键的设计思想技能注册表是让 Agent“知道有这些工具存在”的桥梁。我习惯把所有技能的描述动态加载到一个注册表里并定期发给模型作为可选工具列表。代码大概是这样import yaml from pathlib import Path def load_skill_description(skill_name: str) - dict: desc_path Path(fskills/{skill_name}/description.yaml) with open(desc_path, r) as f: return yaml.safe_load(f) def list_available_skills(): skills_dir Path(skills) skill_names [p.name for p in skills_dir.iterdir() if p.is_dir() and (p / main.py).exists()] return {name: load_skill_description(name) for name in skill_names}当你调用某个技能时不能只是返回一个文本告诉模型“我帮你查完了”而是必须把结构化的输出返回给 Agent 框架让框架继续做下一个决策。所以每个技能的 main.py 都有一个约定统一的入口函数。我定的接口很简单每个技能暴露一个run(input_args: dict) - dict函数。这样无论技能内部是调用外部 API、运行 Python 代码还是解析文件对上层 Agent 来说都是统一的“黑盒”。再说工具接入层。以 PubMed 检索为例E-utilities 是公共接口不需要 key 就能用但频率限制很严格每秒最多 3 个请求。严谨的做法是在技能内部加一个请求节流器确保调用频率不会把自己 IP 封掉。下面是我封装的简化版搜索函数里面既有限流也做了缓存import time import requests import xml.etree.ElementTree as ET from diskcache import Cache cache Cache(cache/pubmed_cache) def esearch(query: str, retmax: int 10) - list[str]: if query in cache: return cache[query] url https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi params { db: pubmed, term: query, retmode: json, retmax: retmax, } resp requests.get(url, paramsparams, timeout30) resp.raise_for_status() data resp.json() id_list data[esearchresult].get(idlist, []) cache.set(query, id_list, expire3600 * 24 * 7) time.sleep(0.34) return id_list代码里加了 diskcache 缓存同一个查询关键词在接下来的一周内直接命中不需要再次打扰服务器。这既提速也降低被封风险。拿到 PubMed ID 列表后再调用 efetch 接口拿文章的详细题录做 XML 解析后转成统一 schema 的 JSON。转换过程要注意别把 authors 字段变成一大长串字符串而是拆成结构化数组方便后续做统计分析。比如“最近三年这个方向哪个机构发文最多”这类问题只需要对结构化数组做个 group-by根本不用再让模型去读原文。3.3 跑一次完整任务从自然语言到带引用的综述报告现在进入完整的运行流程。假设我向 Agent 提的需求是“写一篇关于图神经网络在药物发现中应用的简要综述重点涵盖分子表示学习、属性预测和分子生成三个方向引用真实文献总字数 800 字左右”。主管 Agent 的任务规划模块会先识别出四个关键技能并排好执行序列。第一步是“检索筛选”。主管 Agent 把我给出的主题改写成适合数据库的检索式(graph neural network[Title/Abstract]) AND (drug discovery[Title/Abstract]) AND 2020:2025[dp]交给文献检索技能。文献检索技能从 PubMed 和 arXiv 各拉一批候选文献按年份、被引次数、期刊影响力做一个粗过滤最终保留大约 30 篇进入全文解析阶段。这一步看似简单实际上模型需要判断哪些候选和用户关注的三个方向直接相关不是只要标题里含“graph”就算。为了减少误判我在技能里内置了一个“相关性打分”步骤用 embedding 把标题和摘要与用户 query 的比较相似度低于阈值的直接过滤掉。第二步是“精读证据抽取”。30 篇候选文献里有的能拿到 PDF有的只能拿到摘要。能拿到 PDF 的进入全文解析流程用 PyMuPDF 提取文本再切割成 sentence 级片段后用领域专用模型抽取出“模型架构、数据集、基准方法、关键结果”等证据字段。我测试过许多通用大模型直接读长文的效果结论是别让它一次读完整个 PDF否则关键的数值信息很容易丢失。得先把 PDF 切成若干语义块针对每个块分别抽取最后再由大模型汇总去重。这个过程就是典型的 Skill 层级发挥稳定作用的地方。第三步是“结构生成”。Agent 基于抽取出的真实证据按“分子表示学习、属性预测、分子生成”三个段落组织综述。这一步我特意加了一个硬性约束综述中出现的任何一句关键结论后面的引用编号必须来自前面证据抽取阶段得到的真实文献列表。模型不能凭空加引用也不能把 A 论文的结论安到 B 论文头上。为了让控制更稳妥我不会让模型从零写整篇综述而是让它先写一个 outline我检查 outline 里的粒度合适后再逐段生成。每生成一段就回填一次真实引用从源头上消灭幻觉引用。下面这一步的执行日志类似 Agent 实际跑任务时的截图[Plan] 用户目标: 综述图神经网络在药物发现中的进展 [Step 1] 调用技能 literature_search检索式已生成候选: 278 篇 [Step 1] 筛选后保留: 32 篇相关度 0.75 [Step 2] 调用技能 pdf_parsing成功解析 24 篇8 篇仅有摘要 [Step 2] 抽取证据 156 条其中数值型证据 42 条 [Step 3] 调用技能 evidence_extraction检测到 3 篇文献证据不足已标记为“背景性引用” [Step 4] 调用技能 report_writing生成 outline共 3 个 section [Step 4] 分节生成中当前进度: 2/3 [Step 4] 综述生成完成共 824 字引用文献 21 篇 [Verify] 引用完整性校验通过: 每一条结论均有对应 PMID/DOI [Finish] 报告已写入 outputs/reports/gnn_drug_discovery_2025.md实测下来整个流程在普通配置的机器上跑完约 8 分钟成本主要由 PDF 解析和大模型生成构成。如果是让一个研究生手工做同样的事花掉大半天都算正常。当然这个流程并非完美仍有约 15% 比例的文献会因为 PDF 解析质量差或者原文图表信息缺失导致证据抽取不完整。这也是为什么最终报告生成后我还是会快速扫一眼绝对不会盲信。3.4 编排层代码速写用状态机让 Agent 循环可控在编排层我用了 LangGraph 的图结构来定义 Agent 的状态转移。节点就是各个技能边就是它们之间的执行顺序或条件分支。这里简单展示一个核心代码片段说明“图”如何定义技能链接。下面这个例子我简化了实际项目的分支条件会复杂很多比如当检索结果不够时需要跳回重新生成检索词。但核心思想是一样的状态机控制流程技能只负责执行不让模型随机决定下一步调什么工具。from langgraph.graph import StateGraph, END from typing import TypedDict, Optional class AgentState(TypedDict): user_query: str papers: list evidences: list report: Optional[str] step_input: Optional[str] def node_search(state: AgentState) - AgentState: from skills.literature_search.main import run as search_run result search_run({query: state[user_query]}) return {papers: result[papers]} def node_extract(state: AgentState) - AgentState: from skills.evidence_extraction.main import run as extract_run result extract_run({papers: state[papers]}) return {evidences: result[evidences]} def node_write(state: AgentState) - AgentState: from skills.report_writing.main import run as report_run result report_run({ user_query: state[user_query], evidences: state[evidences], }) return {report: result[report]} graph StateGraph(AgentState) graph.add_node(search, node_search) graph.add_node(extract, node_extract) graph.add_node(write, node_write) graph.set_entry_point(search) graph.add_edge(search, extract) graph.add_edge(extract, write) graph.add_edge(write, END) app graph.compile()这样定义出来的状态流有很强约束力。比如你想确保 Agent 不走回头路就可以在图里加一条禁止边某些节点之间不允许跳转你想加一个先并行做两路文献检索再合并结果的分支LangGraph 也提供了对应的条件边语法。相比直接让大模型在循环里自己决定下一步状态机的好处是你一眼就能从图里看出这个 Agent 的整体工作流排查问题时也能直接定位到是哪一个节点出了问题。4. 实战中踩过的坑与排查实录4.1 把技能包做成“一次性用品”上下文爆炸与任务中断恢复这个错误几乎每个从 Demo 走向生产的人都会犯。你可能觉得“既然模型 token 窗口已经有几十万了那就把所有论文全文都塞进去”结果刚开始跑就发现开销暴涨。我接到过的一个项目里导师让 Agent 精读 40 篇论文并生成对比表格。如果直接把每篇论文全文拷进上下文单是输入 token 就要几十万成本高而且大量 token 被浪费在无关的致谢、参考文献列表等区域上。真正有效的阅读策略是分层加工每一步都做信息压缩先全文解析再按段落做语义检索只把跟主线任务相关的句子送入大模型最后再让大模型输出结构化的证据摘要。每一步都会丢一部分次要细节但换来的是上下文可控、结论准确率显著上升。任务中断恢复的问题也很实际。有一次我在本地跑一个长时间文献筛选任务跑到第 20 篇时笔记本因为断电中断了等我重启后重新运行发现 Agent 从第 1 篇开始重新解析起白白耗掉了大半个小时。这是因为我没有做任务级断点。后来我改了代码在每个技能节点执行完后把当前状态已完成步骤、已处理文献 ID 列表、已抽取的证据序列化到一个task_state.json文件里下次启动时先读这个文件如果有未完成步骤就接着跑。这个改动看似不起眼但省下的时间非常可观而且对长周期科研任务来说几乎是必需的。4.2 工具调用不稳定识别“看起来成功实则失败”的垃圾返回大模型在工具调用时最大的坑不是完全调错而是“返回了一个格式很漂亮但暗含幻觉的结果”。比如让 Agent 从论文里抽取实验数据如果论文里确实没有给出数值模型倾向于根据上下文猜一个“看起来合理”的数字填进去而不是老老实实留空。这在一个用 GNN 预测药物毒性的项目里坑过我模型生成的表格里写了一个对照组 p 值实际原文根本未报告该统计量差点导致后续做 meta 分析的分析师误用。从那以后我在所有涉及数据抽取的技能里都强制加一条规则原文里没有的数值必须留 NULL并标注“原文未报告”不允许用估计值补位。另一种垃圾返回是“复读机式成功”。模型调用了某个工具后并没有真的分析工具返回的内容而是根据自己印象直接把结论写出来。判断方法是做一次输出与工具返回的交叉验证。我给事实性技能增加了“引用锚点校验”任何一句重要的结论后面都必须挂上工具返回中的来源 ID如果 Agent 生成的结论在工具返回里找不到对应支撑该句就会被系统自动标红并退回重写。这种强制绑定虽然让生成过程多了一次校验调用但执行结果的可信度提升了好几个等级。4.3 Agent 循环失控与超时重试为什么一直重复“快好了”工具型 Agent 最大的一个稳定运行阻碍是循环失控和运行超时。我自己遇到过“同样技能反复调用 8 次”的严重案例Agent 每次调用领域检索工具后的结果都是没筛选出符合条件的关键论文于是它换一个检索词再来一遍换了 6 个词之后终于想放弃了但又没有“放弃”协议直接卡死。在排查这类现象时我系统性地发现它们频繁出现在“验证 Agent”观察到的上下文正在快速膨胀的阶段尤其在没有给 Agent 设置最大轮数上限的情况下。比如经典的“the agent execution provider did not respond in time”这类超时信息根本原因往往不是 API 服务慢而是 Agent 已经陷入过长的工具链中总超时预算被某一批次大量重试耗尽。解决办法有几个经验值可以参考。第一设全局最大工具调用轮数。文献综述类任务我设 25 轮跑不完也会强制收束不允许无限循环。第二设置单次工具调用的超时时间PubMed 请求我设 30 秒PDF 解析我设 120 秒到点不再等待直接标记失败并走降级逻辑。第三识别“循环模式”如果模型连续三轮调用了同一个技能且检索关键词变化很小系统认定它陷入了无效搜索自动触发“搜索失败”流程把它引导到“更换检索策略”或“精简问题范围”的子技能上而不是继续让它自由发挥。第四对“重复性达到多少轮就截断”这种问题我会把判断写进 Harness 的退出条件里而不是期望模型自觉。4.4 长任务运行token 成本失控与记忆老化科研任务长度通常远超单次调用范围成本控制得从技能链设计阶段就想好。我最早跑一个 15 篇文献的综述任务把每一步的完整中间结果都传给大模型总 token 数轻松超过百万。后来改用“摘要传递”策略每次传递时只保留高信息密度的字段中间产物压缩率常在 10 倍左右token 成本大幅下降。效果变差的情况也有个别细节可能会被裁掉。所以压缩策略要区分关键字段和次要字段比如定量结果、统计显著性这些关键字段不能丢而方法部分的描述性文本可以适度压缩。长任务里的“记忆老化”同样明显。Agent 启动后读过的第 1 篇论文跑到第 30 篇论文时如果被问到“第 1 篇用的什么模型”它可能已经说得不太准确因为早期记忆被后续信息稀释了。可靠的做法不是尽量保留所有旧记忆中而是在需要跨阶段引用时把关键结果写入结构化表并定期 Refresh。每次摘要生成后都将该摘要反向更新到全局记忆库所以即使模型记不清也能查得到。不匹配自然语言模糊检索查询时直接按字段名读取这种“强缓存弱记忆”的模式在长任务场景下表现得更加稳定。4.5 常见问题快速排查清单我日常排查技能包相关问题一般参照下表中的路线从执行环境、技能定义、工具返回三个层次入手。这张表也适合直接贴在项目文档里当团队的故障手册。问题现象可能原因排查方法Agent 完全不调用技能技能描述不清晰模型没识别出可用工具检查 description.yaml 里的场景描述和动词提示调用了技能但参数全错输入槽位定义不具体优化 input 字段的 description并给每个参数附一个示例值检索结果大量重复上下文记忆没联动技能内查询历史在检索技能内维护一个已查关键词集合重复时自动剔除PDF 解析结果乱码扫描版 PDF 需要 OCR分析引擎不会自动识别增加 OCR 预处理步骤或提示用户提供文本版论文本地和容器环境运行结果不一致依赖版本漂移使用锁文件重装环境并在 CI 中构建固定镜像生成报告引用链接仍无效Agent 依靠印象引用而没有严格回填在 report_writing 技能里做一遍引用锚点校验缺失就重写单轮返回超时Agent 内部循环分支过多缩短工具返回内容并压缩上下文或拆分任务再串行执行长任务中途宕机无法恢复缺任务级状态持久化每个技能执行完将状态写入 JSON重启时读取并断点续跑生成了“看似合理”的错误数值模型擅自补全原文缺失数据在抽取技能里强制原文未有数值一律留 NULL除了这张表有一个底层经验想专门说明技能包的目录命名和描述文案真不能随便起。有一次我把一个“从论文中提取实验方法”的技能命名为extract_methoddescription 又写得很含糊结果模型将该技能用于“提取我上一个问题中的所有方法”这种非预期任务导致几条垃圾调用混入流程。后来我把技能名改成extract_experimental_method_from_pdfdescription 写明“从论文 PDF 的 Methods/Experimental 部分抽取实验步骤、仪器型号、试剂用量”调用准确性立刻变好。想让模型用对工具描述里一定要给出足够的情境线索和反例别指望模型能从精炼短句里自己悟出不变量。5. 技能包的复用与进化我的路线图与实践体会5.1 单个 Agent 到技能集市让一套技能包服务多个 Agent 项目现在回头来看scientific-agent-skills 的最大价值不是某一个 Agent 能跑通而在于它沉淀出的技能可以跨项目复用。最初我为一篇论文的文献综述写了一个 PDF 解析技能后来完全不需要改动就拿去给另一个化学组的专利分析项目使用了后一个项目只要把输出 schema 稍微调整一下即可从“提取方法”切换到“提取权利要求要素”。这种复用得益于一开始就把技能做成了“无状态”的独立模块它不关心调用方是谁只负责完成某件具体的事通过输入参数把差异全部暴露出来。长期演进上我建议团队至少维护一个内部的“技能注册中心”用版本号记录每个技能的迭代历史。当某位同事修复了 PubMed 接口限流处理的 bug 并发布 v1.3 后所有引用了该技能的 Agent 都会自动受益。这个思路和前端社区的 npm 包管理逻辑一致。你如果现在刚开始入坑不必急着搭注册中心但至少要给每个技能目录加一个CHANGELOG.md哪怕只是日期加一行说明也能省掉很多“这个技能谁改过、为什么行为变了”的麻烦。5.2 Agent 框架的选型路线从 LangGraph 到自研 Harness 的渐进式思考关于编排框架的选型不少初学者在第一步就陷入“框架选哪个才对”的焦虑。我自己的经验是先别纠缠框架手里没有跑通过一个小 Agent 之前讨论 LangGraph、CrewAI、AutoGen 的优劣没有任何基础。先找一个教程简单、社区活跃、和 Python 生态契合的框架跑通一个最简流程体会一下 tool calling 和状态传递。之后再开始关注更上游的执行容器概念比如 Harness 这类偏自研方向的东西。Harness 通常承载着更多的上下文管理、生命周期控制和安全边界管理逻辑对框架化场景很有价值但如果你连最基本的检索技能都还没稳定过早引入 Harness 只会让排查复杂度翻倍。等规模到了“需要同时管理 5 个以上 Agent 技能链”的时候再考虑进一步抽象 Agent 流程是合理的。到那个阶段你自然会发现哪些流程是通用的哪些是本项目特有的。把通用部分下沉到框架或 Harness 中把特有部分留成普通技能这个“够用再抽象”的过程比一开始就追求大而全的设计要顺滑得多。5.3 最后几条小技巧来自我这大半年被 Agent 反复摩擦的总结第一给 Agent 设置“不自信标记”。如果 Agent 对某一步的把握不足允许它输出一个confidence: low字段然后我在后续人工复核时优先检查这些低置信区间。别要求模型每次都有 100% 的确定感能用机制暴露不确定性正是自动化系统成熟的表现。第二别把所有技能都暴露给模型。每加一个技能模型的工具选择空间就多一个维度选择失误率也会小幅上升。实际跑综述任务时我只在对应阶段暴露对应的两三个技能而不是同时给它 20 个工具。第三测试 Agent 时不要只测成功路径还要专门设计“刁钻输入”测试比如彻底检索不到文献的情况、PDF 是乱码的情况。Agent 能不能体面地处理“没有结果”这件事往往比能不能顺利跑通理想流程更体现工程质量。这个技能包项目刚做好时我以为最高光的时刻会是某次自动化流程全绿跑通、生成了一份漂亮综述。但后来真正让我觉得值回票价的是实验室一位师弟拿着这份技能包改出了一套药物专利对比分析工具他基本没动底层的技能逻辑只换了检索源和输出模板。那一刻我才意识到给 AI 科学家准备“技能”本质上是在帮每一个具体的研究者积累他们自己的“可复用经验”。这种积累不依赖某一个大模型版本的能力而是沉淀在技能包本身里模型换了一代又一代这些技能仍然可以继续为研究者服务。所以如果你也想入坑科研 Agent我建议不要从吹嘘最宏大的“全自动 AI 科学家”开始而是从把身边一项三十分钟以上的重复性研究工作拆成第一个技能包开始。做完这一个你自然就知道下一步该做什么了。