SciScope TUI SciScope

Use this command to install SciScope TUI with WinGet:

winget install --id=SciScope.SciScopeTUI -e

SciScope TUI is a terminal client designed to provide access to a grounded research agent. It enables users to interact with an AI-powered research tool either offline through a demo mode or by connecting to a SciScope backend service via the SCISCOPE_BACKEND environment variable.

Key Features:

Research Agent Integration: Connects to a backend service that delivers evidence-based responses to research-related queries.
Offline Demo Mode: Offers a self-contained demonstration of the tool's capabilities without requiring an internet connection.
Backend Connectivity: Seamlessly integrates with a remote SciScope backend using the SCISCOPE_BACKEND parameter for enhanced functionality.
Winget Deployment: Available via the Windows Package Manager, allowing users to install and deploy SciScope TUI efficiently using winget commands.

Target Audience and Benefits: Ideal for researchers, students, and professionals seeking evidence-based insights. Users can access a powerful research tool directly from their terminal, enabling them to explore scientific literature, analyze trends, and generate reports without relying on external platforms or services. The ability to run in both online and offline modes ensures flexibility and accessibility for various use cases.

This solution is particularly beneficial for individuals who require quick, reliable access to research tools while maintaining control over their data and environment.

SciScope

SciScope 是一个证据接地的科研文献智能体：用户通过跨平台终端客户端提问，后端以文献检索、趋势分析、论文推荐、证据核查和报告资产为基础给出可追溯回答。发布版默认连接托管后端，普通用户无需本机启动 Python、PostgreSQL 或模型服务。

SciScope TUI product snapshot

快速开始

推荐优先使用 npm，macOS 用户也可以用 Homebrew，Windows 用户也可以用 Scoop。完整下载索引见 docs/release/README.md。

npm install -g sciscope-tui
sciscope-tui

Windows npm 用户如果遇到 GitHub Release 下载或解压失败，可暂时使用 Scoop； npm 修复版 0.2.2 已在源码中准备好，等待 registry 发布。

其他安装方式：

场景	命令	适合谁
跨平台 / 开发者	`npm install -g sciscope-tui`	macOS、Windows、Linux；已有 Node.js 的用户
macOS	`brew tap Timcai06/sciscope && brew trust --cask timcai06/sciscope/sciscope-tui && brew install --cask sciscope-tui`	Homebrew 用户
Windows	`scoop bucket add sciscope https://github.com/Timcai06/scoop-sciscope && scoop install sciscope-tui`	Scoop 用户
无网络演示	`sciscope-tui demo`	不依赖后端的固定演示流程

启动后直接输入科研问题即可；也可以输入 / 查看命令菜单。离线演示：

sciscope-tui demo

开发者连接本地后端：

SCISCOPE_BACKEND=http://127.0.0.1:8000 sciscope-tui

产品边界

Python 是底座：数据治理、RAG、检索、证据接地、Agent 工具编排都在 backend/ 与 src/ 体系中实现。
Go TUI (tui/) 是终端客户端，不承载推理，只消费后端的 SSE 事件。
Web 前端已从当前项目路径移除；主交互端为 Go TUI 与 FastAPI API。

仓库启动面向 Makefile，以下信息优先于旧文档口径。文档总入口见 docs/README.md；日常操作以本 README、tui/README.md、 docs/operations/deploy-hosted-backend.md 和 docs/operations/runbook.md 为准。

当前环境口径

场景	后端	数据库	检索	用途
生产/demo	Render Web Service	Supabase Postgres + pgvector	PostgreSQL FTS + DeepSeek evidence chat；禁用运行时本地 embedding	用户试用、演示视频、npm/Brew/Scoop 默认入口
本地开发	本机 FastAPI	本地 PostgreSQL	full hybrid lexical + semantic retrieval	全量数据、模型实验、报告生成、agent 调试

生产/demo 为小样本 hosted corpus，当前约 220 papers / 467 chunks。本地开发环境保留全量语料、全量向量与更重的语义检索能力。不要把 hosted free demo 描述成全量 semantic production；它是稳定公开入口，架构上可升级到更大实例后开启运行时语义检索。

项目结构速览

目标：把论文源数据变成可检索、可问答、可分析的交付资产（图表、报告、证据链）。
数据入口：data/raw（新增采集 landing zone）、data/raw_canonical（可审计原始底账）、src/harvest（采集/治理入口）。
服务出口：backend/app 的 FastAPI（搜索、趋势、推荐、Agent 流式问答）。
访问端：
- 终端端：tui/（当前主交互端）

项目目录和运行边界见 docs/architecture/project_structure.md。

本地开发

环境要求：

Python 3.11+
PostgreSQL（RAG/检索链条和 /api/search 需要）
Go（如运行 make tui）

标准启动：

make install
make backend

打开：

后端文档：http://127.0.0.1:8000/docs

常见开发运行路径：

后端：make backend 或 make dev。
仅 TUI：发布版直接 sciscope-tui；源码开发用 make backend（先起后端）→ make tui。
本地模型端到端：先保证可用 OpenAI-compatible 服务，再用 make dev-vllm。
离线演示：make tui-demo。
TUI 体检：make tui-doctor。
MCP 服务端：make mcp（把工具暴露给 Claude Desktop 等 MCP 客户端，详见 docs/developer/mcp.md）。

核心命令

数据层与报告

make raw-governance：原始治理到 data/raw_canonical。
make analysis-assets-all：生成 data/analysis/*。
make processed-corpus：生成 data/processed/papers_corpus.json。
make report-figures：生成图表资源到 output/assets/sciscope_data_report/。
make data-report-pdf：生成 sciscope_data_report.pdf。
make project-report-pdf：先刷新项目报告图表，再生成 sciscope_project_report.pdf。
make full-rebuild：从分析资产开始重建入库、向量、模型、图谱与数据报告；原始治理需先跑 make raw-governance。
make data-layer-refresh：分析资产 + 语料 + 报表重建的轻量入口。

data/ 不是 PostgreSQL 的重复备份：它是数据库、RAG、模型、报告的可重建资产层。数据库负责在线查询服务；data/raw_canonical、data/analysis、data/processed/papers_corpus.json、data/processed/paper_chunks.jsonl 负责复现、审计与报告。

报告叙事、截图和 hosted/local 口径见 docs/reports/report-optimization.md。

模型层与工具链

make rag-chunks：构建 RAG 块。
make postgres-load：写入 PostgreSQL。
make postgres-refresh：schema + load 的完整刷新。
make embeddings / make trend-model / make recommend-model / make graph-export：模型/图谱资产构建。
make agent-build：embeddings + trend + recommend + graph 聚合构建。

服务与验证

make test：后端测试。
make test-backend：仅后端测试。
make smoke：基础 API 健康检查。
make agent-smoke：live agent 黑盒验收，检查真实库表规模、skills 工具链路与工具预算。
make vllm-smoke：检查本地 OpenAI-compatible 模型端点。
make tui-build TUI_VERSION=0.2.1：产出 Go 客户端二进制。

Terminal Agent Client（Go TUI）

终端客户端是“协议消费者”：它不承载模型与检索决策逻辑，只消费 POST /api/agent/stream 的 SSE 事件并渲染为可读面板。

启动方式（发布版推荐，默认连接 hosted backend）：

sciscope-tui

源码开发时连接本地后端：

make backend  # 先启动后端 127.0.0.1:8000
make llm      # 可选：本地 LLM 兼容网关（用于真实联网问答）
SCISCOPE_BACKEND=http://127.0.0.1:8000 make tui
make tui-demo # 离线演示流程（无后端）
make tui-doctor # 检查后端/LLM/会话目录/图谱资产

版本与发布链路请见：

tui/README.md
docs/release/README.md

运行时速查

默认环境变量（运行时有默认值）：

SCISCOPE_DATA_PATH=data/sample/papers.sample.json
SCISCOPE_DB_DSN=postgresql://tim@localhost:5432/sciscope
SCISCOPE_USE_MOCK_LLM=true
SCISCOPE_LLM_PROVIDER=deepseek
SCISCOPE_BACKEND 仅用于 TUI 覆盖后端地址；发布二进制已内置 hosted URL。
SCISCOPE_ENABLE_RUNTIME_EMBEDDINGS=false 用于小规格 hosted 服务，避免 Web 容器加载本地 embedding 模型。
Agent 运行时：单一 LangGraph StateGraph（backend/app/agent/langgraph_runtime.py），无运行时开关。

关键 API：

POST /api/agent/stream（SSE）：请求支持 question/history/session_id/retry；SSE 事件 plan/text/tool_call/tool_result/reflect/final/error，并在 meta 中返回 runtime/node/elapsed_ms/session_id/retry，供 TUI 渲染工具时间线与同会话 /retry。
GET /api/ingest/status
GET /api/dashboard/overview
GET /api/disputes（只读争议前线；只包含已采信的正反证据）
POST /api/chat

常见故障（先查这里）

端口不可达：确认 make backend 已启动，访问 127.0.0.1:8000。
TUI 无法显示流式：确认后端先跑，再执行 make tui；必要时设置 SCISCOPE_TUI_ICONS=off。
检索/趋势为空：确认 PostgreSQL 已准备好，执行 make postgres-refresh 或至少 make postgres-load + make rag-chunks。
LLM 报错：切回 SCISCOPE_USE_MOCK_LLM=true 做快速验证；或先 make llm 提供本地模型。
图表/PDF 缺失：检查 data/analysis 和 output/assets/sciscope_data_report，再跑 make report-figures && make data-report-pdf。
项目报告缺失或指标过期：先确认 data/processed 和 output/eval 是否为最新，再跑 make project-report-pdf。

现有边界

该分支的主运行路径是：Python agent/data layer 为核心，Go TUI 为终端消费端。
Web 前端源码已移除；若未来重启 Web 界面，应作为新范围重新设计和接入。
src/data_contracts/ 是共享数据契约层（Paper 模型/loaders/normalize），backend 运行时与 src.harvest 共用；核心数据治理以 src/harvest、src/analysis、src/infra 为准。
src/models/ 是 Python 代码包（嵌入/趋势/推荐脚本）；models/ 是 gitignore 的模型文件资产，二者同名不同物。
DeepSeek 是 hosted/demo 的默认云端模型；确定性本地验证仍可使用 mock 模式，本地 LLM 通路以 make dev-vllm / make llm 为主。

许可证与贡献

SciScope 以 Apache License 2.0 开源。欢迎围绕后端、数据/RAG 管线、Go TUI、打包发布、文档和测试提交 issue 或 pull request；贡献入口见 CONTRIBUTING.md，安全问题请先看 SECURITY.md，社区协作规范见 CODE_OF_CONDUCT.md。