SciTrace

English · 中文

MCP 服务器 — 让 AI Agent 的推理链从上下文窗口搬进数据库。

一行 MCP 配置。两个 Tool。Agent 每次调用 build_trace 记录一个推理步骤，query_trace 随时拉回历史。数据在 SQLite，不在上下文窗口。

🚀 30 秒看效果：

pip install scitrace
scitrace-demo --viz      # 写入一条钙钛矿科研演示链 + 生成可视化

用浏览器打开生成的 scitrace-demo.html：悬停节点看摘要、点击看详情面板、双击折叠子树——找一找那条紫色虚线（backtrack），那是推理链最精彩的部分。

---

为什么不用提示词/Skill？

提示词和 Skill 能做到"让 Agent 输出结构化推理"，但做不到以下五件事。

1. 上下文窗口是稀缺资源，不是仓库

	提示词规定输出结构	SciTrace
10 步后上下文	10 段完整 JSON（500-1500 tokens）堆在窗口里	10 行短调用记录，数据全在 SQLite
50 步后	Agent 开始"遗忘"前面的步骤——窗口被历史推理挤满	上下文干净，需要时 query_trace 精确拉回
跨会话	新会话 = 全部丢失	SQLite 持久化，新会话直接查

提示词方式里，推理链越积越多，抢真实任务的 token 配额。SciTrace 把数据搬出去——上下文窗口用于思考，SQLite 用于存储。

2. 提示词只写不查，SciTrace 可查

提示词: "之前那个假设是什么来着？" → Agent 在 3000 tokens 的聊天记录里翻找 → 可能翻到也可能漏掉

SciTrace: query_trace(type="hypothesis") → 精确返回。不看聊天记录。

结构化查询 = type=backtrack 直接找到所有失败回溯点，type=experiment 列出全部实验步骤，trace_id=xxx 看完整推理链。提示词做不到。

3. DAG 不是扁平的

提示词让 Agent 输出顺序列表。但科研推理不是线性的——它分叉、回溯、有依赖。

h1 (假设) → a1 (分析) → e1 (实验) → b1 (回溯) → e2 (修正) → v1 (验证) → c1 (结论)
                                          ↑
                                    parent_id 显式声明依赖

parent_id 把扁平的列表变成了有向无环图。这个图结构不占用上下文——它存在 SQLite 的外键关系里。

4. 一次开发，所有 Agent 可用

	提示词	Skill	SciTrace
Claude	每 Agent 写一份	每 Agent 写一份	✅ 同一份 MCP 配置
Cursor	每 Agent 写一份	—	✅ 同一份 MCP 配置
Hermes	每 Agent 写一份	每 Agent 写一份	✅ 同一份 MCP 配置
Codex	每 Agent 写一份	—	✅ 同一份 MCP 配置

MCP 是协议标准。写一次服务器，所有 MCP 兼容 Agent 自动获得推理追踪能力。不需要为每个 Agent 移植提示词。

5. 数据能被程序消费

提示词产生的结构化输出只有 LLM 能读。SciTrace 的数据存在 SQLite 里——任何工具都能读：

Python 分析脚本 → 直接读 SQLite
可视化工具     → scitrace-viz 一键出 HTML
CI/CD 流水线   → sqlite3 命令行查询
Jupyter        → import sqlite3 直接分析

不需要过 LLM——数据的消费者可以是代码。

---

架构

Agent (Claude/Cursor/Hermes/Codex)
    │
    │ MCP 协议 (stdio)
    │
    ▼
┌─────────────────────────┐
│   SciTrace MCP Server   │
│                         │
│  build_trace  ← 写入    │
│  query_trace  ← 读取    │
│                         │
│  ↓ SQLite               │
│  steps 表               │
│  - id, parent_id (DAG)  │
│  - type (6 种推理类型)   │
│  - summary, artifacts   │
└─────────────────────────┘

---

快速开始

pip install scitrace

在你的 MCP 客户端配置中添加：

{
  "mcpServers": {
    "scitrace": {
      "command": "python",
      "args": ["-m", "scitrace"]
    }
  }
}

Agent 即可调用 build_trace 和 query_trace。

数据存储

项	默认值	覆盖方式
数据库路径	~/.scitrace/traces.db	SCITRACE_DB 环境变量，或 MCP 配置 args 里加 --db <path>
可视化输出目录	当前工作目录	SCITRACE_OUTPUT 环境变量

{
  "mcpServers": {
    "scitrace": {
      "command": "python",
      "args": ["-m", "scitrace", "--db", "/path/to/custom.db"]
    }
  }
}

可视化

pip install 附带 scitrace-viz 命令——把推理链渲染成完全离线的交互式 HTML（自绘 SVG DAG，零外部依赖，内网/断网环境可用）：

scitrace-viz                 # 可视化最近一条 trace
scitrace-viz <trace_id>      # 可视化指定 trace
scitrace-viz --out ./viz     # 指定输出目录
scitrace-viz --index         # 生成全部 trace 的概览索引页 index.html
scitrace-viz --theme dark    # 指定初始主题（页面内可随时切换）

• 悬停节点看完整摘要；点击节点打开详情面板（父/子步骤、artifacts 文件链接）
• 双击折叠子树；滚轮缩放、拖拽平移、一键适应
• 明暗主题切换（记忆在 localStorage）；含环的推理链自动回退为时间线布局
• 旧版本（v0.1.x）数据库首次打开时自动迁移，原文件备份为 traces.db.bak-<日期>

---

让 Agent 真正开始记录

装好 MCP 只是第一步：Agent 不会主动调用 build_trace，除非你在它的配置里告诉它。官方接入模板（每份 ≤10 行，拿来即用）：

客户端	模板文件	放哪里
Claude Desktop	prompts/claude-desktop.md	项目 Instructions / CLAUDE.md
Cursor	prompts/cursor.md	.cursor/rules/scitrace.mdc
Codex CLI	prompts/codex-agents.md	项目根目录 AGENTS.md
Hermes	prompts/hermes.md	系统提示 / skill

核心约定只有四条：

1. 何时记：完成一个可验证的推理子任务后调用 build_trace——不是每句话都记
2. ID 约定：step_id 只需在 trace 内唯一；trace_id 用有意义的任务名（如 perovskite-2026）
3. 回溯要显式：走不通的方向记 type=backtrack——复盘时最有价值的节点
4. 跨会话恢复：新会话开头 query_trace(trace_id=...) 拉回上下文，不重复问用户

---

两个 Tool

build_trace

记录一个推理步骤。Agent 每次完成一个可验证的子任务时调用。

参数	说明
step_id	步骤唯一标识
trace_id	属于哪条推理链
type	hypothesis / analysis / experiment / verification / conclusion / backtrack
summary	一句话概括这步做了什么
parent_id	依赖哪一步（构建 DAG）
artifacts	关联文件路径

query_trace

按条件查询历史推理步骤。

参数	说明
trace_id	按推理链过滤
type	按类型过滤
limit	返回上限（默认 50，最大 1000）

---

使用示例

一次完整的推理链记录：

build_trace: { "step_id": "h1", "trace_id": "exp-001", "type": "hypothesis", "summary": "假设 P != NP" }
build_trace: { "step_id": "a1", "trace_id": "exp-001", "type": "analysis", "summary": "SAT 是困难的", "parent_id": "h1" }
build_trace: { "step_id": "e1", "trace_id": "exp-001", "type": "experiment", "summary": "运行基准测试", "parent_id": "a1", "artifacts": ["results.csv"] }
build_trace: { "step_id": "c1", "trace_id": "exp-001", "type": "conclusion", "summary": "结论：……", "parent_id": "e1" }

query_trace: { "trace_id": "exp-001" }        → 返回整条链
query_trace: { "type": "experiment" }         → 返回所有实验步骤
query_trace: { "limit": 10 }                  → 最近 10 步

---

开发

git clone https://github.com/Mobai-read/scitrace
cd scitrace
pip install -e ".[dev]"
pytest

详细贡献流程见 CONTRIBUTING.md。

---

对比总结

	提示词	Skill	SciTrace
数据位置	上下文窗口	上下文窗口	SQLite
跨会话持久化	❌	❌	✅
结构化查询	❌	❌	✅
DAG 依赖	❌	❌	✅ (parent_id)
程序可读	❌	❌	✅ (SQLite)
多 Agent 通用	每 Agent 一份	每 Agent 一份	✅ 一份配置
长链推理	挤爆上下文	挤爆上下文	上下文干净

---

文档

• 变更日志
• 安全策略
• 贡献指南
• 开发基线 PRD

---

许可

MIT