企业官网建设流程全解析

做科研的人最近应该都刷到过类似的讨论：一边是「AI 已经能顶一个博士生」的判断，另一边是实验室里真正跑过 Agent 的人说「它连我的实验记录都读不明白」。这两种说法其实都对，只是说的不是同一件事。前者衡量的是模型在标准题目上的单点表现，后者衡量的是能不能把一条完整的研究链路跑通、跑稳、跑得可复现。

本文不打算停在观点层面，而是从工程视角把「科研 Agent」拆开：它的核心机制是什么、工具层怎么写、主循环怎么控、结果怎么评测、哪里最容易翻车。读者对象是已经会写 Python、想在自己的研究或业务里落地 Agent 的开发者，也适合做实验管理、数据分析、文献调研的同学参考。跟着走完，你能得到一个可运行的最小科研助手，包含文献检索、数据统计、引用溯源和离线评测四个模块，代码可以直接复制改造。

1. 从「AI 能不能替代博士生」说到可落地的科研 Agent

1.1 争论背后的真实分歧

把这场讨论摊开看，分歧点其实非常具体。支持方的证据通常是模型能在某些基准测试上拿到不错的分数，比如代码题、数学推导、文献选择题；反对方的证据则是模型会在参考文献上编造作者和期刊、会在多步实验里丢掉中间约束、会把相关性当成因果性。这两类证据并不矛盾，因为它们测的根本不是同一个东西。

基准测试测的是「给定完整上下文、单轮输出、有标准答案」的任务，而科研的真实流程是「问题模糊、上下文散落在几十篇论文和几个 G 的实验数据里、没有标准答案、需要反复试错」。前者是一个信息检索加推理的问题，后者是一个长程规划加状态管理的问题。用一个单轮任务的表现去推断长程任务的能力，本质上和用一次函数调用能不能跑通来推断整个微服务能不能上线是一样的逻辑错误。

所以工程上更靠谱的问法不是「它比博士生强吗」，而是「在我的这条具体链路上，它能稳定完成哪几步，剩下的几步需要人补」。这个问法可以直接转成技术需求：把链路拆成可枚举的步骤，每步都定义输入输出和校验方式，然后逐段压测。

1.2 Agent 与「一次问答」的本质区别

很多人第一次用大模型做科研辅助，方式是打开对话框，把问题一股脑丢进去。这种做法在信息量小的时候体验很好，一旦涉及「先查文献、再筛选、再读全文、再抽数据、再算统计」这种多阶段任务，就会迅速失控。原因很简单：单次问答的上下文窗口是有限的，而研究任务需要的中间状态会不断累积，模型在上下文变长之后对早期约束的注意力会明显衰减。

Agent 的价值就在于把这些中间状态外置。它不再要求模型一次性把所有东西都记住，而是把「查到的文献」「解析出的段落」「算出来的统计量」都变成可以反复读取的外部结果，模型每一步只需要关心「当前状态是什么、下一步该干什么」。这就把一个大而脆弱的推理，拆成了若干个小的、可检查的推理。

换句话说，Agent 不是让模型变聪明了，而是让模型的输出变成了可以被程序校验的对象。这个转变对科研场景特别关键，因为科研最不能接受的就是「看起来对」。

1.3 科研场景下 Agent 的能力边界

把边界说清楚，后面写代码才不会跑偏。根据实际落地经验，可以把科研链路里的任务按可靠性分成三档。

这个分档不是贬低模型能力，而是提醒你把「生成」和「判断」分开。生成可以并行、可以回滚、可以重跑；判断一旦错了，后面所有工作都要推翻。工程上的做法是：让 Agent 尽可能多产草稿和中间产物，把最终判断留一个明确的人工确认点。

2. Agent 做科研的核心概念拆解

2.1 规划、执行、观察的循环结构

几乎所有能跑通多步任务的 Agent，骨架都是同一个循环：模型先根据当前上下文决定下一步动作，程序执行这个动作拿到结果，把结果塞回上下文，再进入下一轮。这个结构常被叫作 ReAct，字面意思就是推理加行动交替进行。

用 ASCII 图表示就是下面这样：

用户任务 | v [模型推理] -- 输出 JSON 指令 --> [程序解析] | | | v | [执行工具函数] | | | v +--------- 观察结果回填 <---- 工具返回值 | v [模型判定信息足够] --> 输出最终答案

这个循环里，真正决定成败的往往不是模型本身，而是两件事：一是模型输出的指令能不能被程序稳定解析，二是工具返回的内容够不够模型做下一步决策。前者靠约束输出格式解决，后者靠工具设计解决。很多「Agent 效果不好」的案例，追根到底都是工具返回了一坨模型看不懂的东西。

2.2 工具签名的设计原则

工具就是 Agent 的手。手好不好用，直接决定它能干成什么事。设计工具签名时有几条经验值得记住。

第一，工具粒度要适中。太细，模型需要很多步才能完成一件事，步数一多出错概率就上去了；太粗，工具内部逻辑复杂，出问题时模型无法定位。一般建议一个工具对应一个明确的动作，参数控制在三个以内。

第二，工具描述要写成「什么时候用它」，而不是「它是什么」。模型在选工具时依赖描述文本，如果描述只写「检索文献」，模型在需要统计数据时也可能误选。写成「根据关键词在本地文献库中检索标题和摘要，返回匹配度最高的若干条，用于查找相关工作」就会准确得多。

第三，工具必须自己处理异常并把错误变成可读文本。工具抛异常直接打崩 Agent 循环是最常见的翻车方式，正确做法是捕获后返回一段模型能理解的话，比如「文件不存在，请检查路径」，让模型有机会换个参数重试。

2.3 检索增强与引用溯源

科研场景对引用的要求远高于普通问答。模型自己「回忆」出来的文献标题、作者、年份，可信度非常低，这一点在大量实测中反复被验证。解决办法不是反复提示「不要编造」，而是从架构上让模型没有机会编造：所有文献信息都必须从检索工具返回，模型只能引用工具给出的 doc_id。

这就是检索增强生成的核心思路。落到代码上就是两步：先检索，把命中的片段连同标识符一起塞进上下文；再要求模型在最终答案里用标识符标注出处。后一步是关键，如果没有强制标注，模型会倾向于把检索到的内容和自己的先验知识混在一起写，你就再也分不清哪句有依据、哪句是幻觉。

2.4 结果自检与不确定性表达

一个成熟的科研 Agent 应该会「说自己不知道」。实现方式有两种，一种是在提示词里明确要求「证据不足时直接说明不足」，另一种是在程序层面做校验，比如最终答案里如果没有出现任何 doc_id，就把这次输出标记为「无引用」，在展示层给出警示。

后一种更可靠，因为它不依赖模型自觉。工程上建议把这类校验做成硬性的后置检查，只要不满足就降级展示或者打回重跑。这比在提示词里加十句「请务必严谨」有效得多。

3. 环境准备与项目结构

3.1 运行环境与依赖说明

本文示例使用 Python 3.10 及以上版本，主要考虑是类型标注和新语法用起来更顺手。依赖库尽量选常见且稳定的：调用大模型用官方 SDK，数据处理用 pandas，PDF 解析用 pypdf，命令行交互直接用标准库，不引入额外框架。

需要提前说明的是，本文调用的是 OpenAI 兼容的 chat completions 接口。市面上多数模型服务都提供兼容层，但具体模型名称、接口地址、参数支持情况各家不同，请以你实际使用的服务文档为准。示例里的默认值都写成了占位符，不要直接拿去跑。

# 文件路径：requirements.txt openai>=1.30.0 pandas>=2.0.0 pypdf>=4.0.0

安装命令如下：

# 创建虚拟环境（可选但推荐） python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate # 安装依赖 pip install -r requirements.txt

如果你的环境里 pypdf 版本较低，可能需要换用 PyPDF2，两者的 API 有差异，导入部分建议写成兼容形式，后文示例会给出。

3.2 目录结构设计

一个容易维护的 Agent 项目，目录划分要比普通脚本严格一些，因为工具、配置、提示词、数据、评测这几块的修改节奏完全不同。示例结构如下：

research_agent/ ├── config.py # 配置与密钥读取 ├── agent/ │ ├── __init__.py │ └── core.py # Agent 主循环 ├── tools/ │ ├── __init__.py │ ├── base.py # 工具注册表 │ ├── literature.py # 文献检索工具 │ ├── analysis.py # 数据统计工具 │ └── pdf_parser.py # PDF 解析工具 ├── data/ │ ├── literature.json # 演示用文献库 │ └── experiments.csv # 演示用实验数据 ├── eval/ │ ├── cases.json # 评测用例 │ └── evaluate.py # 离线评测脚本 ├── workspace/ # Agent 产物输出目录 └── run_demo.py # 入口脚本

把workspace单独拎出来是个小习惯，但很有用。Agent 产生的中间文件、图表、日志都往这里写，清理和备份都很方便，也不会污染源码目录。

3.3 配置管理与密钥安全

密钥绝对不能写进代码。示例统一从环境变量读取，同时在配置类里给出默认值和注释，方便排查。

# 文件路径：research_agent/config.py import os from dataclasses import dataclass, field @dataclass class AgentConfig: """Agent 运行配置，所有敏感信息从环境变量读取。""" # 模型服务地址，请替换为你实际使用的兼容接口地址 base_url: str = field(default_factory=lambda: os.getenv("LLM_BASE_URL", "http://localhost:8000/v1")) # 模型服务密钥 api_key: str = field(default_factory=lambda: os.getenv("LLM_API_KEY", "")) # 模型名称，各家命名不同，务必按文档填写 model: str = field(default_factory=lambda: os.getenv("LLM_MODEL", "your-model-name")) # 单次任务最大循环步数，防止死循环 max_steps: int = 8 # 采样温度，科研场景建议偏低 temperature: float = 0.2 # 单次请求超时时间，单位秒 timeout: int = 60 # 产物输出目录 workdir: str = field(default_factory=lambda: os.getenv("AGENT_WORKDIR", "./workspace")) def validate(self) -> None: if not self.api_key: raise ValueError("缺少 LLM_API_KEY，请通过环境变量配置") if self.model == "your-model-name": raise ValueError("请通过 LLM_MODEL 指定实际模型名称")

设置环境变量时，Linux 和 macOS 用export，Windows 用set，不要把这些命令提交到公开仓库里。

export LLM_BASE_URL="http://localhost:8000/v1" export LLM_API_KEY="sk-你的密钥" export LLM_MODEL="your-model-name"

这里validate()的作用不只是友好提示，更重要的是让配置错误在启动阶段就暴露。Agent 类应用如果配置有问题，往往表现为模型胡言乱语，排查成本很高，提前校验能省掉大量时间。

4. 完整实战：从零搭一个科研文献助手 Agent

接下来把这套东西真正跑起来。我们要做的 Agent 接收一句自然语言任务，能自己决定先查文献还是先算数据，最后给出一份带出处的答复。

4.1 工具注册表与统一错误处理

先写工具注册表。它的职责是保存工具描述供模型选择，并在调用时兜住异常。

# 文件路径：research_agent/tools/base.py from typing import Any, Callable, Dict class ToolRegistry: """工具注册表：负责工具描述生成与安全调用。""" def __init__(self) -> None: self._tools: Dict[str, Dict[str, Any]] = {} def register(self, name: str, description: str, func: Callable[..., Any]) -> "ToolRegistry": if not name or not callable(func): raise ValueError("工具名不能为空且必须可调用") self._tools[name] = {"description": description, "func": func} return self def spec(self) -> str: """生成给模型看的工具清单，一段一行，便于模型逐条对照。""" return "\n".join(f"- {name}: {item['description']}" for name, item in self._tools.items()) def call(self, name: str, **kwargs: Any) -> str: """统一调用入口，任何异常都转成文本返回，避免打断主循环。""" if name not in self._tools: return f"ERROR: 工具 {name} 不存在，可用工具为：{', '.join(self._tools.keys())}" try: result = self._tools[name]["func"](**kwargs) return str(result) except TypeError as exc: return f"ERROR: 工具 {name} 参数不匹配，请检查参数名，详情：{exc}" except Exception as exc: # noqa: BLE001 return f"ERROR: 工具 {name} 执行失败，详情：{exc}"

这里对TypeError单独捕获是刻意的。模型最常见的错误之一就是参数名写错或者漏参数，如果和其他异常混在一起，返回的文本里就没有足够信息提示模型改参数。单独区分之后，模型看到「参数不匹配」往往能自己修正。

4.2 文献检索工具实现

演示用的文献库放在本地 JSON 里，每条记录包含doc_id、title、abstract、year。真实项目里可以换成搜索引擎接口或本地向量库，但工具签名保持一致，Agent 逻辑完全不用改。

[ { "doc_id": "demo-001", "title": "基于图神经网络的分子性质预测方法研究", "abstract": "本文研究图神经网络在分子图表示学习中的应用，提出一种面向分子性质预测的消息传递改进方案，并在多个公开数据集上进行了对比实验。", "year": 2022 }, { "doc_id": "demo-002", "title": "小样本学习在材料发现中的应用综述", "abstract": "本文系统梳理小样本学习在材料发现任务中的方法体系，讨论数据稀缺条件下模型迁移与不确定性估计的若干问题。", "year": 2023 }, { "doc_id": "demo-003", "title": "科研工作流的可复现性度量框架", "abstract": "本文提出一套面向计算类科研工作流的可复现性度量框架，从环境、数据、代码三个维度定义可复现等级。", "year": 2021 }, { "doc_id": "demo-004", "title": "大语言模型辅助文献综述的方法与风险", "abstract": "本文讨论大语言模型在文献综述环节的使用方法与潜在风险，指出引用核验是当前最主要的薄弱点。", "year": 2024 }, { "doc_id": "demo-005", "title": "自动化实验平台的任务调度优化", "abstract": "本文针对自动化实验平台的多任务并发场景，提出一种基于优先级的调度策略，降低实验排队时延。", "year": 2023 } ]

需要说明，上面这些条目是为了演示程序流程构造的示例数据，不是真实论文。如果你的项目要接入真实文献，务必走正规的文献数据库接口，并遵守对应的使用条款。

检索本身用一个轻量的打分函数实现，先做分词，再算一个简化的相似度。真实项目可以换 BM25 或者向量检索，接口不变。

# 文件路径：research_agent/tools/literature.py import json import re from pathlib import Path from typing import Any, Dict, List, Optional class LiteratureStore: """本地文献库，提供关键词检索与按 ID 读取。""" def __init__(self, path: str) -> None: self.path = Path(path) if not self.path.exists(): raise FileNotFoundError(f"文献库文件不存在：{self.path}") self.docs: List[Dict[str, Any]] = json.loads(self.path.read_text(encoding="utf-8")) @staticmethod def _tokens(text: str) -> List[str]: # 英文按词切，中文按单字切，够用即可 return re.findall(r"[a-zA-Z]+|[\u4e00-\u9fa5]", text.lower()) def search(self, query: str, top_k: int = 3) -> List[Dict[str, Any]]: tokens_q = self._tokens(query) if not tokens_q: return [] set_q = set(tokens_q) scored: List[tuple] = [] for doc in self.docs: body = f"{doc.get('title', '')} {doc.get('abstract', '')}" set_d = set(self._tokens(body)) if not set_d: continue # 余弦形式的重合度，长度归一化避免长摘要压制短摘要 overlap = len(set_q & set_d) / ((len(set_q) * len(set_d)) ** 0.5) if overlap > 0: scored.append((overlap, doc)) scored.sort(key=lambda item: item[0], reverse=True) return [ { "doc_id": doc["doc_id"], "title": doc["title"], "year": doc.get("year"), "score": round(score, 4), "abstract": doc.get("abstract", "")[:120], } for score, doc in scored[:top_k] ] def get(self, doc_id: str) -> Optional[Dict[str, Any]]: for doc in self.docs: if doc["doc_id"] == doc_id: return doc return None

search返回的字段是刻意精简过的。摘要只截前 120 个字符，因为完整摘要塞进上下文会快速吃掉预算，而且模型在这一步通常只需要判断「这篇相不相关」，不需要读全文。真正需要全文时，再单独调用按 ID 读取的工具，这种两步走的设计能显著降低整体成本。

4.3 数据统计工具实现

科研 Agent 另一半价值在数据处理。这里给一个基于 pandas 的聚合工具，接收 CSV 路径、分组列和指标列，返回 markdown 表格。让工具直接产出 markdown 有个好处：模型不需要再把结构化数据转成自然语言，直接把表格贴进答案里就行，既准确又省 token。

# 文件路径：research_agent/tools/analysis.py from pathlib import Path from typing import Any, Dict import pandas as pd def aggregate_metrics(csv_path: str, group_by: str, metric: str) -> str: """按分组列聚合指标，返回 markdown 表格字符串。""" path = Path(csv_path) if not path.exists(): return f"ERROR: 数据文件不存在：{csv_path}" try: df = pd.read_csv(path) except Exception as exc: # noqa: BLE001 return f"ERROR: 读取 CSV 失败，可能是编码或分隔符问题，详情：{exc}" for col in (group_by, metric): if col not in df.columns: return f"ERROR: 列 {col} 不存在，现有列为：{', '.join(df.columns)}" if not pd.api.types.is_numeric_dtype(df[metric]): return f"ERROR: 列 {metric} 不是数值类型，无法计算均值" summary = ( df.groupby(group_by)[metric] .agg(["count", "mean", "std", "min", "max"]) .round(4) .reset_index() ) header = "| " + " | ".join(summary.columns) + " |" divider = "| " + " | ".join(["---"] * len(summary.columns)) + " |" rows = [ "| " + " | ".join(str(v) for v in row) + " |" for row in summary.itertuples(index=False) ] return "\n".join([header, divider, *rows]) + f"\n\n数据来源：{csv_path}"

这里几处校验都对应真实踩过的坑。列名写错是最高频的问题，所以错误信息里直接把现有列名全部列出来，模型下一轮基本就能改对。类型检查则是为了防止把字符串列当数值算，pandas 对这种情况有时不报错而是给出奇怪结果，主动拦下来更安全。

配套的演示数据如下：

# 文件路径：research_agent/data/experiments.csv method,dataset,accuracy,f1 GNN,dataset_a,0.812,0.798 GNN,dataset_b,0.785,0.771 MLP,dataset_a,0.744,0.731 MLP,dataset_b,0.729,0.715 RF,dataset_a,0.761,0.752 RF,dataset_b,0.748,0.736

注意 CSV 文件里不要真的写第一行注释，上面只是为了标明路径。实际文件第一行必须是表头。

4.4 Agent 主循环实现

核心循环来了。这里选择让模型输出 JSON 指令而不是依赖各家 SDK 的 function calling 结构，原因是前者通用性更好，换服务商只需要改地址和模型名，解析逻辑不用动。

# 文件路径：research_agent/agent/core.py import json import re from typing import Any, Dict, List, Optional from openai import OpenAI from research_agent.config import AgentConfig from research_agent.tools.base import ToolRegistry SYSTEM_PROMPT = """你是一个严谨的科研助手，通过调用工具来完成用户的研究任务。 可用工具： {tool_spec} 输出要求：每次只能输出一个 JSON 对象，不要输出 JSON 之外的任何文字。 需要调用工具时输出： {"thought": "你的推理过程", "action": "工具名", "action_input": {"参数名": "参数值"}} 信息足够时输出： {"thought": "你的推理过程", "final_answer": "最终回答"} 必须遵守的规则： 1. 工具名必须与清单完全一致，参数名必须与工具说明中的一致。 2. 工具返回 ERROR 时，分析原因后换一种参数或换一个工具，不要用同样的参数重复调用。 3. 最终回答中的每一条事实性结论都要标注出处，格式为 [doc_id: xxx] 或 [data: 文件名]。 4. 证据不足时直接说明不足，禁止补充未经工具返回的信息。 """ class ResearchAgent: """最小可用的科研助手 Agent。""" def __init__(self, config: AgentConfig, registry: ToolRegistry, verbose: bool = True) -> None: config.validate() self.config = config self.registry = registry self.verbose = verbose self.client = OpenAI( base_url=config.base_url, api_key=config.api_key, timeout=config.timeout, ) self.trace: List[Dict[str, Any]] = [] @staticmethod def _extract_json(text: str) -> Dict[str, Any]: """从模型输出中提取第一个完整 JSON 对象。""" match = re.search(r"\{.*\}", text, re.S) if not match: raise ValueError("未找到 JSON 对象") return json.loads(match.group(0)) def run(self, task: str, max_steps: Optional[int] = None) -> Dict[str, Any]: limit = max_steps or self.config.max_steps system_prompt = SYSTEM_PROMPT.replace("{tool_spec}", self.registry.spec()) messages: List[Dict[str, str]] = [ {"role": "system", "content": system_prompt}, {"role": "user", "content": task}, ] for step in range(1, limit + 1): response = self.client.chat.completions.create( model=self.config.model, messages=messages, temperature=self.config.temperature, ) content = response.choices[0].message.content or "" messages.append({"role": "assistant", "content": content}) if self.verbose: print(f"\n===== 第 {step} 步 =====") print(content.strip()[:500]) try: payload = self._extract_json(content) except (ValueError, json.JSONDecodeError) as exc: # 格式错误不直接失败，回一句话让模型自己修 messages.append( {"role": "user", "content": f"输出格式错误（{exc}），请只输出一个合法 JSON 对象。"} ) continue if "final_answer" in payload: answer = str(payload["final_answer"]) self.trace.append({"step": step, "type": "final", "content": answer}) return { "success": True, "answer": answer, "steps": step, "cited": bool(re.search(r"\[(doc_id|data):", answer)), "trace": self.trace, } action = payload.get("action") action_input = payload.get("action_input") or {} if not isinstance(action_input, dict): messages.append({"role": "user", "content": "action_input 必须是 JSON 对象。"}) continue observation = self.registry.call(action, **action_input) self.trace.append( {"step": step, "type": "tool", "action": action, "input": action_input, "output": observation[:800]} ) messages.append( {"role": "user", "content": f"工具 {action} 的执行结果：\n{observation}"} ) return { "success": False, "answer": "达到最大步数仍未得出结论，请检查任务描述或工具能力。", "steps": limit, "cited": False, "trace": self.trace, }

几处设计值得展开说。第一，格式错误不视为致命失败，而是回灌一条提示让模型自己修，这能把大部分偶发的格式问题就地消化掉。第二，cited字段是硬性校验，不管模型自述多么严谨，只要最终答案里没有出现引用标记，就记录为无引用，展示层可以据此加警示。第三，trace完整记录了每一步的工具调用和返回，这是后续排查和评测的基础，比事后再去翻日志可靠得多。

一个需要提前说明的兼容性问题：部分模型服务对消息角色的交替有严格要求，连续两条 user 消息可能被拒绝。如果遇到这类报错，可以在工具结果前包一层 assistant 的简短说明，或者改用该服务提供的工具调用字段。这一点各家差异较大，请按实际文档调整。

4.5 组装入口与运行验证

最后把工具注册和入口串起来。

# 文件路径：research_agent/run_demo.py import json from pathlib import Path from research_agent.agent.core import ResearchAgent from research_agent.config import AgentConfig from research_agent.tools.analysis import aggregate_metrics from research_agent.tools.base import ToolRegistry from research_agent.tools.literature import LiteratureStore def build_registry() -> ToolRegistry: store = LiteratureStore("./research_agent/data/literature.json") registry = ToolRegistry() registry.register( "search_literature", "根据关键词在本地文献库中检索标题和摘要，返回匹配度最高的若干条。参数：query（检索词），top_k（返回条数，默认 3）。用于查找相关工作。", lambda query, top_k=3: json.dumps(store.search(query, int(top_k)), ensure_ascii=False), ) registry.register( "read_literature", "按文献编号读取完整信息，包括标题、年份和完整摘要。参数：doc_id（文献编号，如 demo-001）。用于需要细节时补充阅读。", lambda doc_id: json.dumps(store.get(doc_id) or {"error": "未找到该文献"}, ensure_ascii=False), ) registry.register( "aggregate_metrics", "对实验 CSV 按某列分组统计指标，返回 markdown 表格。参数：csv_path（文件路径），group_by（分组列名），metric（数值指标列名）。用于汇总实验数据。", aggregate_metrics, ) return registry def main() -> None: config = AgentConfig() Path(config.workdir).mkdir(parents=True, exist_ok=True) agent = ResearchAgent(config, build_registry()) task = ( "请查一下和图神经网络做分子性质预测相关的工作，" "并统计 experiments.csv 中不同方法在 accuracy 上的均值，" "最后给出一段简短结论，每个结论都要标注来源。" ) result = agent.run(task) print("\n===== 最终结果 =====") print(result["answer"]) print(f"\n步数：{result['steps']}，是否包含引用标记：{result['cited']}") log_path = Path(config.workdir) / "trace_last.json" log_path.write_text(json.dumps(result["trace"], ensure_ascii=False, indent=2), encoding="utf-8") print(f"调用链已保存至 {log_path}") if __name__ == "__main__": main()

运行方式：

python -m research_agent.run_demo

预期输出大致是两段内容，一段是检索到的文献列表（含demo-001这类编号），一段是按方法分组的 accuracy 统计表，最后是带[doc_id: demo-001]、[data: experiments.csv]标记的结论。如果你的模型第一次就给出了没有引用标记的答案，cited会是False，这时不要急着怀疑模型不行，先检查提示词里的规则有没有被正确替换进 system 内容里。

trace_last.json这个产物很值得养成习惯。每次出问题，先看这个文件里第几步开始跑偏，是工具返回不对，还是模型选错了工具，一眼就能看出来，比对着终端输出翻要快得多。

5. 科研 Agent 的评测：怎么判断它行不行

5.1 评测集怎么设计

回到文章开头的争论。要回答「行不行」，唯一的办法是自己建评测集。评测集不需要很大，二十到五十条就足够暴露主要问题，关键是覆盖典型链路。

建议按三个维度设计用例：检索类（能不能找到正确文献）、计算类（能不能算对统计量）、综合类（多工具串联）。每条用例包含问题、期望命中的 doc_id、期望调用的工具名、是否要求引用。

[ { "id": "case-01", "question": "有哪些工作把图神经网络用于分子性质预测？", "expect_doc_ids": ["demo-001"], "expect_tools": ["search_literature"], "require_citation": true }, { "id": "case-02", "question": "统计 experiments.csv 中各方法 accuracy 的均值", "expect_doc_ids": [], "expect_tools": ["aggregate_metrics"], "require_citation": true }, { "id": "case-03", "question": "文献里提到的可复现性度量框架从哪几个维度定义？", "expect_doc_ids": ["demo-003"], "expect_tools": ["search_literature", "read_literature"], "require_citation": true } ]

5.2 离线评测脚本

评测脚本的逻辑很直白：逐条跑 Agent，检查最终答案里有没有出现期望的 doc_id，调用的工具里有没有覆盖期望工具，以及是否正确带了引用。

# 文件路径：research_agent/eval/evaluate.py import json from pathlib import Path from research_agent.agent.core import ResearchAgent from research_agent.config import AgentConfig from research_agent.run_demo import build_registry def run_eval(cases_path: str) -> None: cases = json.loads(Path(cases_path).read_text(encoding="utf-8")) agent = ResearchAgent(AgentConfig(), build_registry(), verbose=False) total = len(cases) hit_doc = hit_tool = hit_cite = 0 for case in cases: result = agent.run(case["question"]) answer = result["answer"] used_tools = {item["action"] for item in result["trace"] if item["type"] == "tool"} doc_ok = all(doc_id in answer for doc_id in case["expect_doc_ids"]) if case["expect_doc_ids"] else True tool_ok = all(name in used_tools for name in case["expect_tools"]) cite_ok = bool(result["cited"]) if case["require_citation"] else True hit_doc += int(doc_ok) hit_tool += int(tool_ok) hit_cite += int(cite_ok) print( f"[{case['id']}] doc={doc_ok} tool={tool_ok} cite={cite_ok} " f"steps={result['steps']} success={result['success']}" ) print("\n===== 汇总 =====") print(f"用例总数：{total}") print(f"文献命中率：{hit_doc / total:.2%}") print(f"工具覆盖率：{hit_tool / total:.2%}") print(f"引用合规率：{hit_cite / total:.2%}") if __name__ == "__main__": run_eval("./research_agent/eval/cases.json")

运行：

python -m research_agent.eval.evaluate

这套指标不追求绝对准确，它的价值在于可比较。你换了模型、改了提示词、调了工具描述，跑一遍就知道是变好还是变差。没有这个基线，所有关于「效果提升」的判断都是感觉，而感觉在工程上几乎不可靠。

5.3 人工复核与盲评

自动指标只能覆盖「有没有」，覆盖不了「对不对」。比如 Agent 找到了正确的文献，但把它得出的结论说反了，自动评测是发现不了的。所以建议在自动评测之后，对通过用例做一轮人工抽样复核，重点看三件事：结论是否被证据支持、有没有偷换概念、有没有隐藏的不确定性。

条件允许的话，可以做个简化盲评：把 Agent 输出的综述初稿和人工写的初稿混在一起，让同组同学判断哪份是机器写的、哪份更可用。这种测试对判断「能不能替代某个环节」比跑基准分数直观得多，也更贴近真实需求。

6. 常见问题与排查思路

实际跑起来之后，问题大多集中在几类。下面这个表格可以先快速定位，后面几条是频率最高的几个展开讲。

关于「反复调用同一个工具」这一条，展开说一下。这是最典型的 Agent 卡死形态：模型检索了一次没找到想要的，换个说法再检索，还是没找到，然后一直循环。根本原因是检索工具返回的是空列表或者只有标题，模型无法从结果里判断「是关键词不对」还是「库里确实没有」。解决办法是在工具返回里主动带上诊断信息，比如「共匹配 0 条，建议尝试更宽泛的关键词或同义词」。这一句话往往就能把模型从死循环里拉出来。

再看「输出不是 JSON」。除了温度因素，还有一种隐蔽情况是模型在 JSON 前后加了说明文字。主循环里用正则提取第一个花括号块能解决大部分情况，但如果模型输出里先出现了一个不完整的花括号，正则就会截错。更稳的写法是用json.JSONDecoder().raw_decode从每个{位置尝试解析，解析成功即返回。这个改动不大，但能把格式失败的比率明显压下来。

最后是超时。科研类任务经常涉及解析几十页 PDF 或者跑一次较重的统计，单个工具调用可能就要几十秒。如果没有超时控制，一个卡住的工具会让整个任务悬停在那里。建议在工具内部做时间限制，超时后返回「该操作超时，建议缩小数据范围」，让 Agent 有机会换策略。

7. 最佳实践与工程建议

7.1 可复现性从第一天就要抓

科研场景里，可复现性的重要性高于一切。落到 Agent 项目上，至少要做到三点：所有工具调用都以结构化形式落盘到 trace 文件；每次运行记录模型名称、温度、提示词版本；数据文件用相对路径并随项目一起版本管理。

第三点容易被忽视。很多人习惯写绝对路径，本地跑得好好的，换台机器就全崩。统一用相对项目根目录的路径，配合一个ROOT = Path(__file__).resolve().parents[1]做基准，能省掉大量环境问题。

# 文件路径：research_agent/paths.py from pathlib import Path ROOT = Path(__file__).resolve().parent def data_path(*parts: str) -> str: return str(ROOT / "data" / Path(*parts)) def workspace_path(*parts: str) -> Path: target = ROOT.parent / "workspace" target.mkdir(parents=True, exist_ok=True) return target.joinpath(*parts)

7.2 幻觉控制的工程手段

提示词里写「不要编造」是必要的，但远远不够。真正有效的手段是架构级的约束，可以归纳成三层。

第一层是信息隔离。凡是涉及事实的字段，例如文献标题、作者、年份、数值指标，一律只允许来自工具返回，模型在最终答案里只能引用标识符，不能重新组织这些字段。这一层靠工具返回的结构化格式保证。

第二层是输出校验。最终答案里必须出现[doc_id: xxx]或[data: 文件名]形式的标记，没有标记就判定为不合规。这一层靠正则检查，不依赖模型自觉。

第三层是交叉核对。对于引用了具体数值的结论，可以用程序把答案里的数字和工具返回的数字做比对，不一致就报警。这一层实现成本稍高，但对定量结论非常值得做。

三层叠加之后，幻觉不会消失，但会从「悄悄混进结论」变成「触发告警被人看到」，这个差别在科研场景里是决定性的。

7.3 成本与延迟的权衡

多步 Agent 的成本是单次问答的数倍，因为它每一轮都要把完整的历史上下文重新送进模型。控制成本有几条常规手段：工具返回内容做长度截断，摘要类字段控制在几百字符以内；中间结果用结构化数据而不是自然语言描述；把可以并行的事情合并成一次工具调用，例如一次检索返回多条而不是分多次查。

延迟方面，最大的瓶颈通常是模型推理本身。如果任务允许，可以把「规划」和「执行」分离，用能力更强的模型做规划、用更便宜的模型做格式化输出，这样能在效果和成本之间取得不错的平衡。

7.4 安全与合规边界

这一点必须单独强调。Agent 具备执行能力，就必须假设它会被误用。落到具体做法上有几条硬性要求：所有文件操作限定在workspace目录内，禁止工具接收绝对路径；涉及删除、覆盖的操作必须二次确认，或者在实现上直接禁止；调用外部接口时做好频率限制和重试退避，避免对第三方造成压力。

数据方面，实验数据、未发表结果、审稿材料都属于敏感内容，接入任何外部模型服务前都要确认清楚数据流向和使用条款。如果条件不允许，就老老实实在本地跑，宁可效果差一点。

另外，涉及文献数据库、期刊平台的使用，必须遵守对方的授权范围，不要用自动化手段绕过访问限制。这一点不是技术问题，是底线问题。

8. 学习路线与后续扩展方向

回到最初那个问题。跑完这套东西之后，你大概会有自己的判断：Agent 在检索、抽取、统计、格式化这些环节上确实比人快很多，也确实能承担相当一部分重复劳动；但在判断什么值得研究、结论能不能站住脚、哪个方向有前景这些事情上，它目前给不出可靠的答案。所以更准确的表述不是「远超博士生」，而是「在链路的某些环节上效率远超人工，在另一些环节上还差得很远」。

如果你想把这套东西继续做深，有几个方向值得投入。一是把工具层做实，接入真实文献检索接口、接入向量数据库做语义检索、接入实验管理系统的 API，工具越扎实，Agent 的上限越高。二是把评测做细，用例覆盖到你自己领域的具体任务，指标从「命中率」细化到「结论正确率」。三是把流程做稳，加上重试、断点、并发和监控，让它在无人值守的情况下也能跑完一批任务。

代码层面还有两个小练习可以马上动手：给 Agent 加一个write_report工具，把检索结果和统计表格拼成一份 markdown 报告写到workspace；给主循环加一个「相同工具相同参数不重复执行」的短路判断，防止死循环。这两个改动都不大，但能让整套流程从「能演示」变成「能日常用」。

最后提醒一句，无论 Agent 输出多顺眼，凡是准备写进论文、写进报告、写进决策的内容，都要回到原始数据和原始文献核对一遍。工具能帮你省掉搬运的时间，但省不掉确认的责任。