tianshu-research
by yq04
README.md
# Tianshu-Research (天枢理工科研能力扩展包)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](https://github.com/yq04/Tianshu-Research/actions)
[](test/)
[](package.json)
[](figure/)
天枢理工科研能力扩展包（**Tianshu-Research Overlay**）。Tianshu-Research 并非孤立臃肿的第三方科研 Agent，亦非单纯外挂的 MCP Server，而是依附于 **Tianshu-Harness**（天枢智能体运行时）的**第一方原生科研能力扩展包**。
项目秉持天枢的核心哲学——**“一套科研内核，两个交互表面；Harness 负责思考与编排，Research 负责测量、存证与科学验收”**。通过收敛公开工具网关、结构化证据账本（Evidence Ledger）与双重科学门禁（Scientific Gate），在运行时严格杜绝「虚构 DOI、用普通网页搜索冒充学术库、未读全文编造页码与实验数据」等大模型科研幻觉。
---
## 〇、0.2.0 版本亮点（Phase 8 插件侧 / 9A / 9B / 11 / 12）
- **Council 评审契约与 CVM 单向投影**（`integration/`）：reader/reviewer/chair 席位矩阵（任何角色无写/执行权），Council 缺席不通过、多数赞成不覆盖反例 gate、chair 一票否决；科研事实向宿主认知层的字节级确定性只读投影。
- **文献生态连接器**（`connectors/`）：OpenAlex 游标分页与同 DOI 版本合并不丢失、arXiv 跨进程限流（全机 3 秒/请求）、Zotero Web API v3 条件写入（412 冲突不静默覆盖）、离线快照回放（`SNAPSHOT_MISS` 绝不伪造）。
- **Jupyter 交互与清洁复跑**（`notebook/`）：探索 ≠ 复现——乱序 cell 与隐藏状态记录被正式复现门禁诚实拒绝；缺 Jupyter 环境 `blocked` 而非伪造收据。
- **能力基准**（`capability-benchmark/`）：数据集哈希固定、假收据必 fail、p-hacking 必 fail、负结果满分、失败 trial 不出分母；`npm run benchmark:smoke` 离线一键运行。
- **发布准备**（`scripts/`）：`check-release-parity.js` 双仓逐文件哈希 parity 校验（显式白名单、只读不覆盖并发修改）；`capture-host-surface.js` 宿主表面快照（未测宿主如实标注）。
---
## 一、多范式科研工作流矩阵与工程边界
本项目全面吸收了现代科研工作流体系的核心精髓，并将其与天枢原生架构深度融合：
```mermaid
flowchart TD
subgraph L1[第 1 层：科研业务流程层]
direction LR
P1[问题与文献] --> P2[创新与方案] --> P3[实验/代码验证] --> P4[分析与写作] --> P5[审稿与双重质控]
P5 -.->|发现问题·返回迭代| P1
end
subgraph L2[第 2 层：Agent 执行层]
direction LR
A1[Scout 学术侦察员] --> A2[Strategist 方案架构员] --> A3[Coder 实验复现员] --> A4[Writer 论文撰写员] --> A5[Council 双重门禁席]
end
subgraph L3[第 3 层：Skills 与工具层]
S1[单一高内聚 research-flow Skill<br>按需 References 展开]
T1[收敛的 4 大公开工具网关<br>query / evidence / palette / status]
end
subgraph L4[第 4 层：MCP 与协议层]
M1[Tianshu-Research stdio MCP]
M2[Zotero 开源标准导出<br>CSL-JSON / RIS 替代 EndNote]
M3[天枢原生能力面<br>Bash / Python / LSP / Office]
end
subgraph L5[第 5 层：知识与资源底座]
K1[云端学术图谱<br>OpenAlex 2.5 亿实体 + arXiv API]
K2[本地轻量结构化证据账本<br>sources / evidence / claims .jsonl]
K3[轻量章节切块<br>read_section 定向精读]
end
L1 === L2
L2 === L3
L3 === L4
L4 === L5
```
### 深度研判：吸收什么 vs 坚决摒弃什么
| 架构层级 | 工作流核心吸收点 (YES) | 坚决摒弃的过度设计与陷阱 (NO) | 决策依据与工程边界 |
| :--- | :--- | :--- | :--- |
| **第 1 层：业务流程层** | **解耦为五大自适应科研范式矩阵**：按需分流至 literature（文献）、empirical（数据实证）、theoretical（理论推导）、benchmark（工程跑分）与 hypothesis（敏捷假说）。 | 摒弃“一刀切必须无脑跑完 5 阶段瀑布流”；由任务目标与输入材料自适应生成最小操作 DAG。数据分析任务产生 0 文献请求。 | 满足不同学科与任务深度需求，避免轻量学术查询或纯代码/数据分析产生沉重流程包袱。 |
| **第 2 层：Agent 执行层** | **系统化映射为天枢原生的 WorkOrder 角色模板**（Scout, Strategist, Coder, Writer, Gatekeeper），通过宿主原生的 `/team` 与 `/council` 分波调度。 | **坚决不在插件内新造 5 套割裂的 Agent 运行时**；避免多进程重复通信开销与独立的调度器混乱。 | 宿主已具备顶级的认知虚拟机（CVM）与多智能体分波引擎，插件专注做好“量具与门禁”。 |
| **第 3 层：Skills 工具层** | **坚守单一高聚合 Skill（`research-flow`）**，内部以按需 References 下钻；工具面**严格收敛为 4 大公开网关**。 | **坚决不拆分成 8 个独立 Skill 塞入环境**；严禁把细碎小动作暴露为公开顶级工具。 | 严格保护 DeepSeek 前缀缓存！过多的细碎工具会稀释模型注意力、打碎 KV Cache 前缀指纹。 |
| **第 4 层：MCP 协议层** | 1. **全面拥抱开源 Zotero**：提供标准 CSL-JSON 与 RIS 导出动作，对接社区开源 `zotero-mcp`；<br>2. 写作与图表复用宿主已有环境与 Office 工具。 | **坚决摒弃商业闭源的 EndNote**；严禁在插件内重复造轮子实现 Code 或 Word 读写能力。 | 用户明确要求用 Zotero 替代 EndNote。宿主已有完备的系统级工具，保持插件纯净度。 |
| **第 5 层：知识与资源层** | **吸纳轻量 RAG 精髓**：<br>1. 全局检索依托 OpenAlex 2.5 亿学术图谱与 arXiv API；<br>2. 本地依托 Git 友好的结构化 JSONL 证据账本；<br>3. 章节切块（`read_section`）按需窄读取。 | **坚决不内嵌重型本地向量数据库（如 Chroma/LanceDB）**；严禁引入数百 MB 本地二进制 C++ / ONNX 依赖。 | 保持零外部二进制依赖与跨平台轻量性；结构化证据账本足以提供确定性物理定位与零幻觉 Grounding。 |
---
## 二、收敛的 4 大公开工具网关
所有底层能力（检索、单篇解析、材料切块、证据账本、科学门禁、图表配色）统一收敛至 4 个 Discriminated Union 工具网关，公开工具 Schema 预算严格控制在约 850 tokens：
1. **`research_query` (统一学术检索与单篇解析网关)**
- `action: "search_papers"`：并发检索 arXiv 与 OpenAlex 开放文献。
- `action: "resolve_paper"`：按 arXiv ID、abs/pdf 链接或 DOI 查询单篇文献元数据，直链 OA PDF 与官方 HTML。
2. **`research_evidence` (结构化证据账本、章节精读与科学门禁网关)**
- `action: "ingest_document"`：导入纯文本/HTML 论文材料至工作区（安全单段 docId，拒绝二进制 PDF 混入），建立全文 Grounding 基准。
- `action: "read_section"`：按章节定向提取已入库材料（默认截断至 2000 字符内，支持 offset 分页），**严格压制上下文暴涨，将单轮精读交互注入的 token 量从 2.5 万压制至 1000 以内**。
- `action: "add_source"`：录入参考文献元数据。
- `action: "add_evidence"`：记录包含真实物理 Locator（章节、行号、字符区间或已核实页码）与原文摘录的证据片段。
- `action: "add_claim"`：基于已录入证据创建科学主张，建立双向追踪链。
- `action: "query_evidence"`：按来源、支持/反驳关系或关键词检索证据片段。
- `action: "get_summary"`：统计当前工作区账本整体规模。
- `action: "verify_ledger"`：执行科学门禁审查（默认 90% Locator 覆盖门槛、全文 Grounding 摘录匹配、小枚举支持关系、占位符拦截）。
- `action: "export_csl_json"`：将账本数据导出为国际标准 Citation Style Language JSON 格式（`.rivet/research/export/literature.csl.json`）。
- `action: "export_ris"`：将账本数据导出为通用 Research Information Systems 格式（`.rivet/research/export/literature.ris`），一键拖入 Zotero。
3. **`journal_palette` (顶刊出版规范配色网关)**
- 查询 100 套顶刊出版规范配色（Nature, Science, IEEE, ColorBrewer, Okabe-Ito 色盲友好色板）。内存即时计算，零依赖。
4. **`research_status` (科研工作区状态诊断)**
- 快速获取当前工作区路径、证据账本统计（Sources/Evidence/Claims）、检索引擎配置与顶刊色板角色目录。
---
## 三、真实实测四大隐患治理与生产级防护
在实机 DeepSeek-V4 长会话测试中，我们深入剖析了遥测日志，落地了四大针对性防护：
### 1. 防 20 万 Token 撑爆机制（DeepSeek 缓存友好）
- **现象**：大模型对话历史具有单调累积性。若模型用 bash 或 `read_file` 把上百 KB 的整篇论文全量回显至对话，单会话上下文十余轮即从 3.3 万暴涨至 20.7 万 tokens（Prompt 累计达 651 万 tokens），导致首字延迟（TTFT）恶化至 3.5s ~ 5.6s。
- **治理**：引入 `read_section` 窄动作，并在 Skill 中确立纪律：长文必须静默存盘后定向读取目标章节（单次限 2000 字符），将单轮增量压缩 95% 以上，真正发挥 DeepSeek 95%~99% 前缀缓存命中率的高吞吐优势。
### 2. 外部学术源防风控与限流保护
- **OpenAlex 礼貌池接入**：在 `search.js` 中自动注入 `&mailto=` 参数（支持 `OPENALEX_MAILTO` 环境变量，缺省合规回退），接入官方 10 req/s 的 Polite Pool；可选支持 `OPENALEX_API_KEY`。
- **arXiv 3 秒节流调度器**：内置基于内存 Promise 的队列调度器，强制发往 arXiv 的请求间隔严格 `>= 3000ms`，杜绝突发流量封禁。
- **优雅降级**：结构化捕获 429 与 403 异常并输出友好提示，保证并发检索时单源失败不崩溃。
### 3. TUN 代理 Fake-IP (198.18.0.0/15) 避坑
- **现象**：Windows 下 Clash / Mihomo 等 TUN 代理会将境外学术域名解析为 198.18.x.x 假网段，触发宿主内核的 SSRF 安全防御。
- **治理**：在学术卡片中自动提供 arXiv 原生在线阅读直链（`- html: https://arxiv.org/html/<id>`）；在 Skill 中规范静默脚本下载后导入，禁止盲目重试 `web_fetch`。
### 4. 项目级配置隔离与日常使用零干扰 (Zero-Pollution Guide)
- **为什么不推荐全局常驻？** 全局常驻会占用约 850 tokens 的 System Prompt 工具定义，分散常规编程注意力；若在会话中途开关 MCP，工具集的变动会打碎 System Prompt 前缀指纹，摧毁 DeepSeek KV 缓存。
- **推荐方案**：遵循「项目级配置优先于全局配置」哲学，仅在科研工程根目录下配置 `.rivet-config.json`：
```json
{
"mcp": {
"servers": {
"tianshu-research": {
"command": "node",
"args": ["D:/1_Research/Develop_Research/plugins/tianshu-research/mcp-server.js"]
}
}
}
}
```
> **配置格式说明**：`mcp.servers` 是天枢的原生项目配置格式（写于项目根目录 `.rivet-config.json` 或 `rivet.json`）。外部宿主（如 Cursor）在 `.cursor/mcp.json` 中使用顶层 `mcpServers` 格式：
> ```json
> {
> "mcpServers": {
> "tianshu-research": {
> "command": "node",
> "args": ["D:/1_Research/Develop_Research/plugins/tianshu-research/mcp-server.js"]
> }
> }
> }
> ```
日常通用编程项目保持纯净的 26 个核心工具面，实现 **0 额外 Token 消耗、0 缓存抖动、0 注意力干扰**。
---
## 四、Zotero 现代文献生态对接（替代 EndNote）
本项目全面对接开源 **Zotero** 生态，彻底告别商业闭源的 EndNote（详见 [docs/zotero-integration.md](docs/zotero-integration.md)）：
1. **一键导出标准格式**：
- 导出 CSL-JSON：`research_evidence(action="export_csl_json")`
- 导出 RIS：`research_evidence(action="export_ris")`
2. **导入 Zotero 客户端**：打开 Zotero 点击 **文件 → 导入 → 选择 .rivet/research/export/literature.ris** 即可秒级结构化入库。
3. **对接社区 `zotero-mcp`**：支持直接通过标准 MCP 协议与本地 Zotero 知识库进行双向检索与条目同步。
---
## 五、五大自适应科研场景范式实战矩阵
天枢科研彻底打破旧有的单向瀑布流，基于 `workflows/router.js` 将科研任务自适应路由至五大范式，产生**最小操作依赖图 (DAG)**，拒绝无脑全量调用。
### 范式 1：数据驱动实证 (Empirical Paradigm)
- **典型任务**：“清洗我的风洞实测 CSV 数据，计算均值并按 95% 置信区间出图。”
- **自适应行为**：识别 `.csv` 输入与统计目标，直接路由至 `empirical`，**产生 0 次文献检索或论文查询**。
- **操作序列**：`data.inspect@1` → `data.prepare@1` → `statistics.compare@1` / `statistics.fit@1` → `figure.render@1`。
- **科学门禁**：核验 `data-quality`、`statistical-validity` 与 `figure-traceability`，杜绝大模型臆造虚假置信度。
### 范式 2：理论推导自洽 (Theoretical Paradigm)
- **典型任务**：“推导 Navier-Stokes 柱坐标展开并验证量纲齐次性与无粘极限。”
- **自适应行为**：识别方程与推导目标，直接路由至 `theoretical`，无需构造虚拟 DOI 或数据集。
- **操作序列**：`theory.dimension@1` → `theory.symbolic@1` → `theory.limit@1` → `theory.numeric-check@1`。
- **科学门禁**：核验 `dimensional-consistency`（SI 基本量纲严格守恒）与 `symbolic-physical`（边界极限退化一致）。
### 范式 3：工程评测消融 (Benchmark Paradigm)
- **典型任务**：“对已有的 ResNet 代码进行 3 组单变量消融实验并监控延迟与显存。”
- **自适应行为**：识别代码输入与跑分目标，直接路由至 `benchmark`，不安排 Scout 文献侦察员。
- **操作序列**：`benchmark.plan@1` → `benchmark.run@1` → `benchmark.compare@1`。
- **科学门禁**：核验 `benchmark-validity`（单一变量隔离与公平计算预算）与 `reproducibility`（环境指纹与不可篡改的 RunReceipt）。
### 范式 4：敏捷假说回环 (Agile Hypothesis Loop)
- **典型任务**：“提出并快速验伪损失权重猜想，支持非线性试错。”
- **自适应行为**：识别可证伪命题，建立假设演进会话（`proposed -> testing -> (supported | refuted | inconclusive) -> revision`）。
- **科研哲学**：**负结果 (refuted) 是合规的第一类科研发现**！失败实验绝不使用 git 清场抹杀，而是保留反例并自增 Revision 继续演进；受 `maxIterations` 预算约束，超额优雅停下如实报告。
### 范式 5：文献初筛与精读 (Literature Paradigm)
- **典型任务**：“检索 arXiv 与 OpenAlex 上关于量子退相干最新研究论文并建立综述账本。”
- **自适应行为**：仅当明确涉及论文、DOI、arXiv 时才激活文献网关，采用静默导入与 `read_section` 定向切片阅读，保护 20 万 Token 窗口。
- **交付出口**：支持导出标准 CSL-JSON 与 RIS 格式，无缝导入 Zotero 开源生态。
---
## 六、Python 绘图伴生库
将 `figure/journal_palette.py` 与 `figure/journal_palette.json` 放置于用户绘图脚本同级目录：
```python
import matplotlib.pyplot as plt
import numpy as np
from journal_palette import journal_palette, apply_journal_style
# 应用顶刊排版规范 (Nature / Science 风格)
apply_journal_style()
# 获取色盲友好色板 (Okabe-Ito)
colors = journal_palette('colorblind')
fig, ax = plt.subplots(figsize=(6, 4))
x = np.linspace(0, 10, 100)
for i in range(len(colors)):
ax.plot(x, np.sin(x + i * 0.5), color=colors[i], label=f'Series {i+1}')
ax.set_title("Journal Figure Demonstration")
ax.legend(loc='upper right', frameon=False)
plt.show()
```
---
## 七、快速开始 (Quickstart)
### 方式 A：作为独立 stdio MCP 服务运行
```bash
# 启动 MCP 服务 (JSON-RPC 2.0 stdio)
node mcp-server.js
```
### 方式 B：在天枢 CLI 中使用
```bash
# 1. 快捷检查科研工作区状态
/research-status
# 2. 启动科研检索初筛
/research physics-informed neural networks
```
### 方式 C：在天枢桌面端 (Tauri) 启用
进入桌面端 **Settings → MCP 服务 →「科研文献」→ 点击启用**。
---
## 八、自动化测试与质量指标
项目包含严谨完备的自动化测试套件，坚守通过即止（Stop on Green）纪律：
```bash
# 运行全量 Node.js 单元测试（86 项测试全部 100% GREEN）
node --test test/*.test.js
# 运行 Python 色板插值与样式单测（6 项断言全部通过）
python test/test_journal_palette.py
```
---
## 九、目录结构全景
```text
Tianshu-Research/
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions 持续集成自动化测试
├── commands/
│ ├── research.md # /research 斜杠指令
│ └── research-status.md # /research-status 诊断指令
├── compute/
│ ├── compute-gateway.js # 渐进式科学计算网关
│ └── sympy_runner.py # SymPy 符号代数执行器
├── docs/
│ ├── smoke.md # 冒烟测试手册
│ ├── tianshu-research-capability-map.md # 顶层全景架构地图与全链路设计
│ ├── tianshu-research-plan.md # 架构规划案
│ └── zotero-integration.md # Zotero 与 zotero-mcp 现代文献对接指南
├── document/
│ └── document-parser.js # 科学文档章节切块与真实物理 Locator 解析
├── figure/
│ ├── journal_palette.json # 100 套顶刊出版色板数据
│ └── journal_palette.py # Python 顶刊绘图伴生库
├── gates/
│ └── scientific-verifier.js # 科学门禁审计器 (Evidence Ledger 闭环校验)
├── jobs/
│ └── job-manager.js # 异步长时间任务状态机
├── ledger/
│ └── evidence-ledger.js # 结构化证据账本核心读写与 CSL-JSON/RIS 导出
├── skills/
│ └── research-flow/
│ ├── SKILL.md # 智能体科研工作流技能规范 (防撑爆与避坑指南)
│ └── references/
│ ├── cvm-reflective-flow.md # CVM 反思型科研工作流实战模版
│ ├── reading-card.md # 精读卡规范
│ ├── polishing.md # 学术润色不变量保护规范
│ └── team-templates.md # 五阶段科研多 Agent 协作与双重门禁模版
├── test/
│ ├── arxiv-sample.xml # 离线 Atom 样卷
│ ├── compute.test.js # 符号计算单测
│ ├── document.test.js # 文档解析与真实定位单测
│ ├── gateway.test.js # 网关工具单测 (包含 read_section 与导出)
│ ├── job.test.js # 异步任务单测
│ ├── ledger.test.js # 证据账本、CSL-JSON 与 RIS 导出单测
│ ├── mcp-server.test.js # MCP JSON-RPC 2.0 协议一致性测试
│ ├── search.test.js # arXiv / OpenAlex 解析与 3s 节流单测
│ └── test_journal_palette.py # Python 色板单测
├── tools/
│ └── research-status.js # 状态诊断工具实现
├── figure.js # Node 端色板插值与角色查询
├── gateway-document.js # 文档解析网关内部实现
├── gateway-evidence.js # 证据账本与章节精读公开网关
├── gateway-job.js # 异步任务网关内部实现
├── gateway-query.js # 学术检索公开网关
├── index.js # 插件导出入口
├── mcp-server.js # 标准 stdio MCP 协议服务
├── package.json # 模块清单
├── search.js # 学术文献检索、礼貌池与节流实现
├── tool-contracts.js # 收敛的 4 大工具契约与 Schema 校验
├── HANDOFF.md # 综合交接文档 (写给无上下文的后续开发者)
├── THIRD_PARTY_NOTICES.md # 第三方开源声明
├── LICENSE # Apache-2.0
└── README.md # 项目全景说明
```
---
## 十、许可证与致谢
- 本项目遵循 [Apache-2.0](LICENSE) 许可证。
- 色板数据整理自 ColorBrewer 2.0 (Apache 2.0)、Okabe-Ito (CC0) 及公开科研绘图规范，详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
- 学术数据接口来自 [arXiv API](https://arxiv.org/help/api) 与 [OpenAlex API](https://openalex.org/)。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues