awesimon/research-agent-harness

研究代理框架

构建能够研究、推理、追踪和引用的代理。

研究代理框架是一个插件驱动的代理框架，用于多源研究和基于证据的答案。它提供了代理式 RAG 应用在生产环境中所需的执行循环、工具编排、持久状态、流式事件、引用验证，以及受 DeepSeek 启发的 Web 界面。

它被设计为一个基础，而非单一用途的聊天机器人：添加一个检索连接器，描述其路由元数据，然后让框架通过同样可追踪的工具协议将其暴露出来。

为什么选择研究代理框架

大多数 RAG 演示止步于“检索一些片段，然后让模型总结它们”。研究代理框架将周围的运行时视为一等系统：

- 代理框架控制轮次、工具预算、超时、并发、重试、优雅收尾以及模型协议适配器；
- 证据账本将来源记录规范化为不可变的证据对象，而不是信任工具返回的文本；
- 引用编译器解析 OpenAI 官方的自定义检索标记，验证来源引用，并输出 output_text URL 注释；
- 轨迹账本持久化推理、助手输出、工具调用、工具结果和终止状态，以便可重连的 UI 渲染；
- Cordis 插件层使来源连接器和产品功能可以独立添加和移除。

其结果是，代理的答案可检查、可恢复，并与支持它们的记录相关联。

能力

- 有界代理循环，支持 Anthropic Messages 和 OpenAI 兼容适配器；
- 带验证、超时和并发限制的 JSON Schema 工具契约；
- 逐步披露的 SKILL.md 工作流；
- OpenAlex、官方 arXiv 和 NCBI PubMed 检索工具；
- 仅追加的 SQLite 事件日志，支持用户绑定会话和后台运行；
- 可重连的 SSE，支持游标重放（Last-Event-ID / after）；
- 服务器拥有的引用编号、验证、ACL 钩子和悬停元数据；
- 标准与深度研究编排模式；
- 可选的深度思考策略，用于更审慎的证据分析；
- 可展开的推理和工具轨迹、会话历史以及轨迹视图；
- 优雅的部分答案收尾，而不是向用户显示预算失败；
- 基于 React/Cordis 的前端，支持基于插件的 UI 组合。

架构

User / API / UI ── POST run ──► RunManager (browser-independent task)
▲                              │
│ reconnectable SSE           ▼
└──── seq cursor ───── append-only events / SQLite
│
▼
AgentHarness
│
├── ContextCompiler ──► skill catalog + citation protocol
│
├── LLM adapter ──────► Anthropic or OpenAI-compatible endpoint
│          │
│          ▼ tool calls
├── ToolRegistry ─────► 校验 / 超时 / 并发
│          │
│          ├── load_skill
│          ├── openalex_search
│          ├── arxiv_search
│          └── ncbi_pubmed_search
│
├── Evidence Ledger ──► 规范化、不可变的来源记录
│
└── CitationCompiler ─► output_text.text + url_citation 注解

检索结果以块级来源的形式暴露给模型，并带有稳定 ID，例如 turn0block0，以及 OpenAI 推荐的私有 Citation Marker 语法（\uE200cite\uE202turn0block0\uE201）。服务器会解析并校验这些标记，在显示前将其移除，并返回干净的 output_text.text 以及 OpenAI 兼容的 url_citation 注解。已知的提供方偏差（例如 [cite]turn0block0[/cite]）仅在此解析器边界处被规范化；无效或虚构的 ID 仍会被拒绝，且这两种语法都不会通过公开响应或流暴露。浏览器直接从类型化消息渲染注解；公开协议中不包含任何引用占位符或全局注册表。请参阅官方引用格式指南和网络搜索引用输出。

智能体模式

编辑器提供两个互补的控制项：

- Standard 保持检索自适应，并在问题不需要外部研究时倾向于给出简洁答案；
- Deep Research 强制进行来源检索，收集多条相关记录，并要求执行框架在回答前对证据进行核对；
- Deep Thinking 是一项独立的执行框架策略，要求模型在规划、检查证据和解决矛盾上投入更多精力。

Deep Research 和 Deep Thinking 是每次运行的显式策略，而非隐藏的提示词约定。它们可以组合使用，且两者都会向持久化的 run_started 事件添加可观察的元数据。

前端技术栈

前端遵循 DeepSeek Harness Web 技术栈：React 18、TypeScript 6、Vite 6、Zustand 4.4.7、Immer 10.1.1、TanStack Virtual、pnpm 和 CSS Modules。app/static 下已检入的生产包包含可调整大小的三栏 AppFrame、项目/工作区分组、用于未关联对话的独立 Recent 区域、语义化对话节点、可展开的工具行、共享的详情检查器，以及经过过滤/虚拟化的轨迹时间线。它直接使用 MIT 许可的 @deepseek-ai/dsh-client-ui-primitives 包来实现 Markdown、代码高亮、展开行、JSON 检查、悬停卡片、图标和状态指示器。FastAPI/SSE 适配器和项目持久化仍为应用专属；显示层复用 DeepSeek Harness 的 Cordis 运行时、RPC 契约、Session 对象层和 ui-workspace。保留的本地工作区适配器未在当前 SaaS 配置中暴露。
DeepSeek 名称和品牌资产未用作产品标识。上游署名和 MIT 声明位于 frontend/THIRD_PARTY_NOTICES.md。

运行
bash
cd research-agent-harness
uv sync --extra dev
cp .env.example .env

编辑 .env 并设置 LLM_API_KEY。不要提交 .env。

Cordis 生产构建包已检入，因此运行 Python 服务不需要前端构建。frontend/ 是保留的 Cordis 之前版本的 UI 源码，并非当前应用所服务的构建包。

对于本项目使用的阿里云百炼兼容端点：
dotenv
LLM_BASE_URL=https://llm-7i80wcrjtcx6gbdo.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
LLM_API_STYLE=openai
LLM_AUTH_MODE=auto
LLM_MODEL=deepseek-v4-flash-0731
LLM_API_KEY=your-key

启动 API 和 UI：
bash
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

打开 http://localhost:8000。API 文档位于 /docs。

运行测试：
bash
uv run pytest -q
cd frontend && pnpm test

先运行确定性的单元/集成覆盖测试，然后针对正在运行的服务器运行可选的真实模型评估用例：
bash
uv run python scripts/run_evals.py --case rag_definition --case hyaluronic_earliest

真实测试套件报告完成情况、来源路由精确度、引用有效性、无回退/预算失败、轮次、工具调用以及每个用例的延迟预算。用例定义位于 evals/cases.yaml；最新检入的结果记录在 evals/REPORT.md 中。

API

非流式聊天
bash
curl http://localhost:8000/api/chat \
-H 'content-type: application/json' \
-d '{
"message": "Find recent papers about agentic RAG for scientific research",
"require_sources": true,
"run_mode": "research",
"thinking_mode": true
}'

run_mode 接受 standard 或 research；thinking_mode 是可选布尔值。浏览器编辑器将这些偏好存储在本地，并在下一次运行时发送。

响应在 content[0] 中携带最终文本：
json
{
"content": [{
"type": "output_text",
"text": "A source-backed answer.",
"annotations": [{
"type": "url_citation",
"start_index": 0,
"end_index": 23,
"url": "https://example.org/source",
"title": "Source title"
}]
}]
}

流式聊天

持久协议将命令提交与事件传递分离：
text
POST /api/runs
GET  /api/sessions/{session_id}/stream?user_id=...&after={last_seq}
GET  /api/sessions/{session_id}/events?user_id=...&after={last_seq}
GET  /api/runs/{run_id}?user_id=...
GET  /api/sessions?user_id=...
GET  /api/workspaces?user_id=...
POST /api/workspaces?user_id=...
PATCH|DELETE /api/workspaces/{workspace_id}?user_id=...
POST /api/runs 立即返回 202。即使浏览器断开连接，Agent 仍会继续运行。每个 SSE 帧都有一个 id，等于持久化 SQLite 事件序列号。EventSource 使用 Last-Event-ID 重新连接；调用方也可以显式发送 after。历史追赶采用先订阅后读取并按序列去重的方式，因此事件在从重放到实时投递的交接过程中不会丢失。

持久化的流式事件包括 reasoning_delta、assistant_delta、tool_call、tool_result、citation_validation，以及终止事件 run_completed / run_failed。增量写入会被合并，以减轻 SQLite 压力，同时不损失重放保真度。

兼容端点 POST /api/chat/stream 仍然会发出：

- event：持久化的 harness 生命周期事件；
- result：最终的 ChatResponse；
- error：终止性错误；
- done：流终止。

与旧实现不同，断开此响应不会取消运行。

用户与会话绑定

运行请求接受 user_id 和 session_id。会话会永久绑定到创建它的第一个用户 ID；跨用户读取、继续、运行检查和引用解析都会返回 403。这些 ID 建立的是应用层所有权，而不是身份验证——生产部署应从已认证的主体派生 user_id，而不是信任请求输入。

workspace_id 是可选的。在项目内创建的会话会持久化该关联；没有该关联的会话会显示在“最近”下。删除项目只会移除工作区注册，并将其对话移至“最近”；对话历史不会被删除。项目是 SaaS 侧的对话分组，不会选择或存储用户目录。底层工作区路径契约仍然保留，以供未来的本地工作区模式使用。

引用详情
text
GET /api/answers/{answer_id}/citations/{citation_id}

此端点将引用元数据解析为底层证据。在真实的多用户部署中，在返回摘录之前，应同时在源适配器和此端点中实施授权。

默认的 PublicEvidenceAuthorizer 仅允许 acl_ref 为 public 的证据。内部连接器应设置应用特定的 ACL 引用，并向 create_app 注入一个 EvidenceAuthorizer，用于评估已认证的请求主体。

添加工具

定义一个 Pydantic 输入契约，以及一个返回 ToolExecutionResult 的异步处理器：
python
class SearchInput(BaseModel):
query: str

async def search(input: BaseModel) -> ToolExecutionResult:
request = SearchInput.model_validate(input)
return ToolExecutionResult(content=f"Searched for {request.query}")

registry.register(ToolSpec(
name="search",
description="Search an internal source.",
input_model=SearchInput,
handler=search,
))
对于检索工具，将每条源记录规范化为一个 Evidence 对象。测试框架会集中将这些记录转换为官方可引用块；连接器编写的文本不是引用协议，而 Evidence 对象仍是权威的审计记录。

添加技能

创建 skills//SKILL.md：
markdown

name: my-workflow
description: When and why the agent should use this workflow.
allowed_tools:
- search

Workflow

Detailed instructions loaded only when the agent calls load_skill.

初始系统上下文中只放置技能元数据。完整指令通过 load_skill 工具逐步披露。

引用保证与限制

内置验证器保证：

- 每个发出的注释都引用当前运行中返回的可引用来源；
- 模型虚构的来源 ID 会被拒绝；
- 私有模型标记和原始来源 ID 在显示前会被移除；
- 注释范围与干净的输出文本一起持久化；
- 来源摘录、定位符、哈希和检索时间仍可供审计；
- 数值声明在区域设置/数量级归一化后进行检查（1,600、1600、4,400 万、44 million）；
- 附近没有引用的数值声明会产生警告。

内置的语义支持检查有意保持保守且基于词汇。对于高风险部署，在将 partial 引用改为 verified 之前，应添加专门的蕴含验证器或人工审核。

外部 API 注意事项

- NCBI 要求 E-utilities 客户端发送应用程序名称和电子邮件。配置 NCBI_EMAIL；如果需要更高的请求限制，请添加 NCBI_API_KEY。
- OpenAlex 是快速的通用学术索引。时间查询首先形成按相关性排序的候选集，然后在本地排序，以免较弱的古老匹配排在相关论文之前。
- arXiv API 要求客户端避免快速重复调用。适配器会串行化调用并保持三秒间隔。
- 如果公开部署，UI 应说明对 arXiv 数据的使用。此演示保持所有来源名称真实，且不暗示背书。

生产环境加固清单

- 将单进程 SQLite 连接替换为 PostgreSQL，以支持多个工作进程；
- 加密或脱敏敏感事件负载；
- 实施连接器级和引用详情级 ACL；
- 将 shell/浏览器工具放入操作系统或容器沙箱；
- 为每个有副作用的工具添加幂等键；
- 添加每用户预算和速率限制；
- 评估检索召回率、引用覆盖率、引用蕴含、延迟和恢复行为。

循环与规划行为

- 最后一轮不暴露任何工具，并明确要求模型基于检索到的证据完成回答。
- 轮次和工具调用预算会返回可用的最佳带引用部分答案；它们不会变成 HTTP 502 错误。
- 一个模型响应中的独立工具调用会在可配置的信号量下并发执行。
- 单源问题在获得一个包含至少三条记录的成功结果集后停止检索；显式多源问题最多可使用 MAX_RETRIEVAL_ROUNDS。
- 等效的工具名称/参数调用会被生成指纹，并在一次运行中被跳过。
- 工具注册携带路由元数据（kind、best_for、parallel_safe），这些元数据会被编译进规划提示中，鼓励选择来源，而不是推测性地扇出。
- 无效的来源 ID、缺失的引用和数值冲突会导致引用验证失败。如果模型没有返回可用的最终文本，服务器会返回一个确定性的、有引用支持的文献回退结果，而不会添加模型记忆中的断言。