天枢理工科研能力扩展包（Tianshu-Research Overlay）。Tianshu-Research 并非孤立臃肿的第三方科研 Agent，亦非单纯外挂的 MCP Server，而是依附于 Tianshu-Harness（天枢智能体运行时）的第一方原生科研能力扩展包。
项目秉持天枢的核心哲学——“一套科研内核，两个交互表面；Harness 负责思考与编排，Research 负责测量、存证与科学验收”。通过收敛公开工具网关、结构化证据账本（Evidence Ledger）与双重科学门禁（Scientific Gate），在运行时严格杜绝「虚构 DOI、用普通网页搜索冒充学术库、未读全文编造页码与实验数据」等大模型科研幻觉。
- 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宿主表面快照（未测宿主如实标注）。
本项目全面吸收了现代科研工作流体系的核心精髓，并将其与天枢原生架构深度融合：
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
| 架构层级 | 工作流核心吸收点 (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；2. 写作与图表复用宿主已有环境与 Office 工具。 |
坚决摒弃商业闭源的 EndNote；严禁在插件内重复造轮子实现 Code 或 Word 读写能力。 | 用户明确要求用 Zotero 替代 EndNote。宿主已有完备的系统级工具，保持插件纯净度。 |
| 第 5 层：知识与资源层 | 吸纳轻量 RAG 精髓： 1. 全局检索依托 OpenAlex 2.5 亿学术图谱与 arXiv API； 2. 本地依托 Git 友好的结构化 JSONL 证据账本； 3. 章节切块（ read_section）按需窄读取。 |
坚决不内嵌重型本地向量数据库（如 Chroma/LanceDB）；严禁引入数百 MB 本地二进制 C++ / ONNX 依赖。 | 保持零外部二进制依赖与跨平台轻量性；结构化证据账本足以提供确定性物理定位与零幻觉 Grounding。 |
所有底层能力（检索、单篇解析、材料切块、证据账本、科学门禁、图表配色）统一收敛至 4 个 Discriminated Union 工具网关，公开工具 Schema 预算严格控制在约 850 tokens：
-
research_query(统一学术检索与单篇解析网关)action: "search_papers"：并发检索 arXiv 与 OpenAlex 开放文献。action: "resolve_paper"：按 arXiv ID、abs/pdf 链接或 DOI 查询单篇文献元数据，直链 OA PDF 与官方 HTML。
-
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。
-
journal_palette(顶刊出版规范配色网关)- 查询 100 套顶刊出版规范配色（Nature, Science, IEEE, ColorBrewer, Okabe-Ito 色盲友好色板）。内存即时计算，零依赖。
-
research_status(科研工作区状态诊断)- 快速获取当前工作区路径、证据账本统计（Sources/Evidence/Claims）、检索引擎配置与顶刊色板角色目录。
在实机 DeepSeek-V4 长会话测试中，我们深入剖析了遥测日志，落地了四大针对性防护：
- 现象：大模型对话历史具有单调累积性。若模型用 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% 前缀缓存命中率的高吞吐优势。
- OpenAlex 礼貌池接入：在
search.js中自动注入&mailto=参数（支持OPENALEX_MAILTO环境变量，缺省合规回退），接入官方 10 req/s 的 Polite Pool；可选支持OPENALEX_API_KEY。 - arXiv 3 秒节流调度器：内置基于内存 Promise 的队列调度器，强制发往 arXiv 的请求间隔严格
>= 3000ms，杜绝突发流量封禁。 - 优雅降级：结构化捕获 429 与 403 异常并输出友好提示，保证并发检索时单源失败不崩溃。
- 现象：Windows 下 Clash / Mihomo 等 TUN 代理会将境外学术域名解析为 198.18.x.x 假网段，触发宿主内核的 SSRF 安全防御。
- 治理：在学术卡片中自动提供 arXiv 原生在线阅读直链（
- html: https://arxiv.org/html/<id>）；在 Skill 中规范静默脚本下载后导入，禁止盲目重试web_fetch。
- 为什么不推荐全局常驻？ 全局常驻会占用约 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"] } } } }
日常通用编程项目保持纯净的 26 个核心工具面，实现 0 额外 Token 消耗、0 缓存抖动、0 注意力干扰。配置格式说明：
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"] } } }
本项目全面对接开源 Zotero 生态，彻底告别商业闭源的 EndNote（详见 docs/zotero-integration.md）：
- 一键导出标准格式：
- 导出 CSL-JSON：
research_evidence(action="export_csl_json") - 导出 RIS：
research_evidence(action="export_ris")
- 导出 CSL-JSON：
- 导入 Zotero 客户端：打开 Zotero 点击 文件 → 导入 → 选择 .rivet/research/export/literature.ris 即可秒级结构化入库。
- 对接社区
zotero-mcp：支持直接通过标准 MCP 协议与本地 Zotero 知识库进行双向检索与条目同步。
天枢科研彻底打破旧有的单向瀑布流，基于 workflows/router.js 将科研任务自适应路由至五大范式，产生最小操作依赖图 (DAG)，拒绝无脑全量调用。
- 典型任务：“清洗我的风洞实测 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，杜绝大模型臆造虚假置信度。
- 典型任务：“推导 Navier-Stokes 柱坐标展开并验证量纲齐次性与无粘极限。”
- 自适应行为：识别方程与推导目标，直接路由至
theoretical，无需构造虚拟 DOI 或数据集。 - 操作序列：
theory.dimension@1→theory.symbolic@1→theory.limit@1→theory.numeric-check@1。 - 科学门禁：核验
dimensional-consistency（SI 基本量纲严格守恒）与symbolic-physical（边界极限退化一致）。
- 典型任务：“对已有的 ResNet 代码进行 3 组单变量消融实验并监控延迟与显存。”
- 自适应行为：识别代码输入与跑分目标，直接路由至
benchmark，不安排 Scout 文献侦察员。 - 操作序列：
benchmark.plan@1→benchmark.run@1→benchmark.compare@1。 - 科学门禁：核验
benchmark-validity（单一变量隔离与公平计算预算）与reproducibility（环境指纹与不可篡改的 RunReceipt）。
- 典型任务：“提出并快速验伪损失权重猜想，支持非线性试错。”
- 自适应行为：识别可证伪命题，建立假设演进会话（
proposed -> testing -> (supported | refuted | inconclusive) -> revision）。 - 科研哲学：负结果 (refuted) 是合规的第一类科研发现！失败实验绝不使用 git 清场抹杀，而是保留反例并自增 Revision 继续演进；受
maxIterations预算约束，超额优雅停下如实报告。
- 典型任务：“检索 arXiv 与 OpenAlex 上关于量子退相干最新研究论文并建立综述账本。”
- 自适应行为：仅当明确涉及论文、DOI、arXiv 时才激活文献网关，采用静默导入与
read_section定向切片阅读，保护 20 万 Token 窗口。 - 交付出口：支持导出标准 CSL-JSON 与 RIS 格式，无缝导入 Zotero 开源生态。
将 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()# 启动 MCP 服务 (JSON-RPC 2.0 stdio)
node mcp-server.js# 1. 快捷检查科研工作区状态
/research-status
# 2. 启动科研检索初筛
/research physics-informed neural networks进入桌面端 Settings → MCP 服务 →「科研文献」→ 点击启用。
项目包含严谨完备的自动化测试套件，坚守通过即止（Stop on Green）纪律：
# 运行全量 Node.js 单元测试（86 项测试全部 100% GREEN）
node --test test/*.test.js
# 运行 Python 色板插值与样式单测（6 项断言全部通过）
python test/test_journal_palette.pyTianshu-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。