# SciTrace

[![PyPI](https://img.shields.io/pypi/v/scitrace)](https://pypi.org/project/scitrace/)
[![Python](https://img.shields.io/pypi/pyversions/scitrace)](https://pypi.org/project/scitrace/)
[![License](https://img.shields.io/github/license/Mobai-read/scitrace)](LICENSE)
[![CI](https://github.com/Mobai-read/scitrace/actions/workflows/ci.yml/badge.svg)](https://github.com/Mobai-read/scitrace/actions/workflows/ci.yml)

[English](https://github.com/Mobai-read/scitrace/blob/main/README.en.md) · [中文](https://github.com/Mobai-read/scitrace/blob/main/README.md)

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

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

**🚀 30 秒看效果：**

```bash
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   │
└─────────────────────────┘
```

---

## 快速开始

```bash
pip install scitrace
```

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

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

Agent 即可调用 `build_trace` 和 `query_trace`。

### 数据存储

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

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

### 可视化

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

```bash
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`**，除非你在它的配置里告诉它。

**规范源**：[`prompts/RULES.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/RULES.md)（何时记 / 记什么 / 何时查）。各客户端模板是压缩版，冲突时以 RULES 为准。

| 客户端 | 模板文件 | 放哪里 |
|:---|:---|:---|
| Claude Desktop | [`prompts/claude-desktop.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/claude-desktop.md) | 项目 Instructions / `CLAUDE.md` |
| Cursor | [`prompts/cursor.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/cursor.md) | `.cursor/rules/scitrace.mdc` |
| Codex CLI | [`prompts/codex-agents.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/codex-agents.md) | 项目根目录 `AGENTS.md` |
| Hermes | [`prompts/hermes.md`](https://github.com/Mobai-read/scitrace/blob/main/prompts/hermes.md) | 系统提示 / skill |

硬规则摘要：

1. **何时记**：可验证子任务结束后才 `build_trace`；走不通**必须** `backtrack`；会话结束前落库
2. **记什么**：`trace_id` 整任务固定；`summary` 一行=做了什么+学到什么；`parent_id` 连成 DAG
3. **何时查**：新会话 / 从失败点续作 / 早期步骤被挤掉时先 `query_trace`；禁止让用户重讲库里已有历史
4. **边界**：只记录、只查询——不控制推理路径

---

## 两个 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 步
```

---

## 开发

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

详细贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md)。

---

## 对比总结

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

---

## 文档

- [变更日志](CHANGELOG.md)
- [安全策略](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)
- [开发基线 PRD](docs/PRD.md)

---

## 📣 分享 / 引用

把 SciTrace 推荐给朋友，或嵌入到你的项目里：

- **GitHub**: <https://github.com/Mobai-read/scitrace>
- **PyPI**: <https://pypi.org/project/scitrace/>

在你的 README 里加一个徽章：

```markdown
[![PyPI](https://img.shields.io/pypi/v/scitrace)](https://pypi.org/project/scitrace/)
```

任何环境一条命令安装：

```bash
pip install scitrace
```

---

## 许可

MIT