Tianshu-Research (天枢理工科研能力扩展包)

天枢理工科研能力扩展包（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 宿主表面快照（未测宿主如实标注）。

Related MCP server: OpenAlex MCP Server

一、多范式科研工作流矩阵与工程边界

本项目全面吸收了现代科研工作流体系的核心精髓，并将其与天枢原生架构深度融合：

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 坚决摒弃什么

二、收敛的 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：

  {
    "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 格式：

  {
    "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）：

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 放置于用户绘图脚本同级目录：

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 服务运行

# 启动 MCP 服务 (JSON-RPC 2.0 stdio)
node mcp-server.js

方式 B：在天枢 CLI 中使用

# 1. 快捷检查科研工作区状态
/research-status

# 2. 启动科研检索初筛
/research physics-informed neural networks

方式 C：在天枢桌面端 (Tauri) 启用

进入桌面端 Settings → MCP 服务 →「科研文献」→ 点击启用。

八、自动化测试与质量指标

项目包含严谨完备的自动化测试套件，坚守通过即止（Stop on Green）纪律：

# 运行全量 Node.js 单元测试（86 项测试全部 100% GREEN）
node --test test/*.test.js

# 运行 Python 色板插值与样式单测（6 项断言全部通过）
python test/test_journal_palette.py

九、目录结构全景

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 许可证。

• 色板数据整理自 ColorBrewer 2.0 (Apache 2.0)、Okabe-Ito (CC0) 及公开科研绘图规范，详见 THIRD_PARTY_NOTICES.md。

• 学术数据接口来自 arXiv API 与 OpenAlex API。