内容
# Noesis：生成式知识引擎
Noesis（前身为NeuroNews）通过摄取文档（新闻、博客、论文、记录），从中挖掘论点和证据，并通过两个界面展示所有内容：
- **生成式用户界面**，没有固定的页面：每个屏幕都是一个布局，在运行时根据自然语言意图规划，适应实际存在的数据、启用的知识领域和操作员的习惯；
- **MCP能力平面**，其中每个子系统都是一个工具服务器，UI、开发代理和自主代理都与之组合。
能力平面不仅用于读取。代理提供新的知识领域：它们建立命名空间知识图，选择和附加提供数据的来源，运行管道，UI通过工具发现为这些领域增长面板。完整的设计存在于[MCP重构计划](docs/architecture/MCP_REARCHITECTURE_PLAN.md)中。
---
## 三大支柱
1. **生成式画布.** 前端没有固定的视图。每个屏幕都是一个`ui-spec-v1`文档，根据意图规划（例如“比较气候政策的出口框架”），验证对抗合约，并从43种面板类型注册表中渲染，这些面板类型建立在一套小的可重用图表基元上。唯一的控件是一个命令栏；规划器在您输入时运行。
2. **MCP能力平面.** 十六个子系统MCP服务器暴露了平台：摄取、论点挖掘、证据和OSINT、知识图、配置、研究、血统、安全等。面板目录、面板数据和LLM规划器都基于工具发现和工具调用。
3. **代理配置的知识.** 审计代理主机在配置、OSINT和生成式UI平面上运行分析师和调查代理。代理在配额和批准防护栏下部署知识图及其自己的存储和管道，每个运行都被预算、允许列出和记录为可回放的记录。
---
## 功能
- **自适应生成式UI.** 每个屏幕都根据意图规划为验证的`ui-spec-v1`文档（启发式，或当配置密钥时由LLM），并适应仓库数据可用性、已安装的领域包和操作员的别针和静音。可以保存画布、重新打开、原地完善，并通过只读链接共享。参见[docs/genui.md](docs/genui.md)。
- **论点挖掘.** 检测主张、分类立场、识别框架（经济、安全、人道主义、法律、政治、科学等），提取演员和实体提及，并跟踪政策立场如何演变。
- **事实检查和验证.** 将主张链接到裁决，评估独立来源数量的验证，标记无来源的断言，并保持公共记录与自身不一致的矛盾账本。
- **OSINT调查表面.** 实体档案、关系路径、重建的时间线和摄取的开放来源的出处跟踪，所有这些都受到严格的证据纪律约束（每行都引用；未引用的条目被标记，从不隐藏）。敏感工具默认关闭，背后有一个标志。
- **来源透明度.** 通过框架多样性、主张归因率和立场中立性对每个出口进行评分，推广到任何来源类型，并具有每周快照和火花线历史。
- **数据科学分析作为工具.** 异常检测、领先滞后、叙事聚类、覆盖率预测、语义漂移、图科学和显著性测试是可组合的工具，报告诚实的 不确定性（置信区间和预测带，绝不是裸点）。
- **领域包.** 知识领域是可安装的`noesis-pack-v1`清单，具有自己的源类型、增强器、规划器词汇和面板。研究包（引用图、场地可信度、文献主张）是一个一流的第二领域；金融和法律领域通过配置单独建立。
- **摄取.** Scrapy爬虫与Playwright和Selenium渲染JavaScript繁重的页面，加上Atom和RSS博客观察列表，馈送到合约验证的管道。
- **NLP和知识图.** 命名实体提取、情感评分、关键词趋势和知识图链接，具有社区和中心性分析。
---
## 架构
### 堆栈
| 层 | 技术 |
|---|---|
| 前端 | React 18, Vite, TypeScript, TanStack Query, Tailwind CSS with shadcn/ui |
| 后端 | FastAPI, uvicorn |
| 分析仓库 | DuckDB (本地文件，单写入器) |
| 论点挖掘 | distilbert with heuristic fallback, scikit-learn, spaCy |
| 爬取 | Scrapy, Playwright, Selenium |
| 流程 | Apache Airflow |
| MLOps | MLflow |
| 向量搜索 | Qdrant, PostgreSQL with pgvector |
| 对象存储 | S3-compatible (MinIO) |
| 流 | Kafka |
| 能力平面 | FastMCP servers (stdio and Streamable HTTP) |
### 本地优先
每个外部服务都有一个本地主机默认值。环境变量使用`NOESIS_`前缀，`NEURONEWS_`作为连续性的备用。 将它们设置为指向生产中的托管等价物：
```text
NOESIS_DB_PATH data/local_warehouse.duckdb # DuckDB 仓库路径
S3_ENDPOINT_URL http://localhost:9000 # MinIO
DYNAMODB_ENDPOINT_URL http://localhost:8000 # DynamoDB Local
NEPTUNE_ENDPOINT ws://localhost:8182/gremlin
```
### MCP能力平面
每个子系统都是一个FastMCP服务器。 读取工具针对仓库运行，永远不会与API写入器冲突，因此对于开发代理和实时UI都是安全的。 生成式UI面板目录源自工具发现，领域包作为连接的服务器到达，配置工具在运行时建立新的知识图。
| 服务器 | 焦点 |
|---|---|
| `pipeline_mcp` | 连接器、摄取阶段、文章统计和分析工具（异常、领先滞后、叙事、预测、漂移、情感、立场、冲突） |
| `argument_mcp` | 主张、立场、框架、演员、出口聚类和评分、立场漂移、基准 |
| `osint_mcp` | 验证、矛盾扫描、来源可靠性、实体档案、关系路径、时间线重建、来源跟踪、调查审计 |
| `kg_mcp` | 知识图统计、实体、社区、中心性、纠正、演变话题 |
| `provisioning_mcp` | 部署、附加来源和管道、摄取、状态、列表、视图、拆除、命名空间知识图谱的血统 |
| `research_mcp` | 引用图、场地可信度、文献主张 |
| `sources_mcp` | 来源配置文件、可信度、比较、出口集群 |
| `domain_packs_mcp` | 启用、禁用、运行增强器、获取UI标志 |
| `blog_mcp` | 订阅、摄取和收获Atom和RSS观察列表 |
| `contract_mcp` | 列表、获取和验证数据合约 |
| `lineage_mcp` | 命名空间、节点、血统、影响、运行历史 |
| `dataset_mcp` | 训练数据集统计、模式、标签分布、采样 |
| `monitoring_mcp` | 当前和历史指标和摘要 |
| `security_mcp` | 安全态势、秘密和TLS检查、备份、DB权限 |
| `schema_mcp` | 表、模式、路由、钩子、模拟导出 |
| `noesis_mcp` | 通过Streamable HTTP的外部生成视图服务器 |
---
## 入门指南
### 1. 克隆
```bash
git clone https://github.com/Ikey168/Noesis.git
cd Noesis
```
### 2. 安装依赖
```bash
pip install -r requirements.txt
cd apps/web && npm install && cd ../..
```
### 3. 运行API
```bash
NEURONEWS_DEV_MODE=true \
NOESIS_DB_PATH=/tmp/noesis-dev.duckdb \
uvicorn src.api.app:app --port 8012
```
`NEURONEWS_DEV_MODE=true`禁用WAF，以便开发请求不会被拒绝。 使用单独的`NOESIS_DB_PATH`以避免锁定主仓库文件。
### 4. 运行前端
```bash
cd apps/web
npm run dev # http://localhost:5173
```
React应用在无法访问API时，会回落到捆绑的演示数据，因此画布适用于UI开发。
### 5. 运行测试
```bash
pytest # 单元和集成测试
npx tsc --noEmit -p apps/web/tsconfig.json # TypeScript类型检查
python scripts/genui/codegen.py --check # 生成的genui工件是当前的
```
### 6. 其他入口点
```bash
# 论点挖掘模型基准和合并门
python scripts/benchmark_models.py
python scripts/benchmark_models.py --gate
# 训练模型（在没有检查点的情况下回落到启发式）
python -m src.argument_mining.train_claim --data data/argument_mining
# 爬虫
python -m src.scraper.run --spider bbc
# Docker
docker compose up --build
```
---
## 生成式画布
前端没有固定的视图。 每个屏幕都是一个画布：一个`ui-spec-v1`布局，由`POST /api/v1/ui/generate`（或当后端无法访问时由客户端规划器）根据意图生成，并从43种面板类型的注册表中渲染。 面板跨越文章和库文档、趋势和事件集群、情感和主张、框架和立场、演员立场和冲突、出口排名和聚类、实体图、研究家族、配置的知识图和OSINT表面。
面板建立在`apps/web/src/components/charts/`中的七个可重用的图表基元上：`LineBand`（带有置信带的线）、`TimelineAxis`（日期事件轴）、`Sankey`（分层流）、`BarKit`（分组和发散条形图），以及`Heatmap`、`EntityGraph`和`Sparkline`。 每个基元都为不同数据层上的多个面板提供服务。
唯一的控件是一个命令栏：规划器在您输入时运行，显示解析的意图令牌和布局的实时预览，然后再提交它。 空画布显示实时管道信号而不是问候语。 布局适应仓库数据可用性、启用的领域包和操作员的别针、静音和交互历史。 画布可以本地保存，可以通过后续指令原地完善，可以通过只读链接共享。 参见[docs/genui.md](docs/genui.md)。
---
## 代理、包和配置
这些表面在默认情况下处于关闭状态的特性标志后面：
| 标志 | 启用 |
|---|---|
| `NOESIS_GENUI_LLM` | LLM规划器（有根基的，使用工具）代替启发式规划器 |
| `NOESIS_GENUI_DATA_PROXY` | 通过`POST /api/v1/ui/data`代理的MCP进行实时面板数据 |
| `NOESIS_PACKS_ADMIN` | 包安装和发布路由 |
| `NOESIS_AGENT_API` | 分析师和调查代理路由 |
| `NOESIS_AGENT_TRANSPORT` | 代理运行的`local`（进程内）或`live`（真实MCP主机） |
| `NOESIS_OSINT_GATED_TOOLS` | 敏感的OSINT工具，除非明确启用，否则保持关闭状态 |
| `NOESIS_ENABLED_PACKS` | 启动时加载的领域包 |
- **领域包**是可安装的`noesis-pack-v1`清单：一个包声明其源类型、增强器、规划器关键词、UI标志和面板，并且注册表保留不可变的版本。 包显示其面板和词汇，而无需编辑核心目录。
- **代理**在三个平面（配置、OSINT、生成式UI）上运行，通过预算令牌、强制执行允许列表和审计每个工具调用的运行时。 运行可以调度在进程内或针对实时MCP主机，并且每个运行时都会产生可回放的记录。
- **配置**允许代理部署具有附加存储和管道的命名空间知识图，在配额和批准防护栏下，具有幂等更新和血统。 金融和法律领域以这种方式建立，无需核心代码更改。
---
## 关键仓库表
| 表 | 包含 |
|---|---|
| `news_articles` | 摄取的文章和元数据 |
| `argument_claims` | 检测到的主张与归因和事实检查裁决 |
| `source_stances` | 按主题划分的来源立场聚合 |
| `stance_drift_events` | 检测到的立场逆转 |
| `document_frames` | 每文档框架得分（七个维度） |
| `document_actors` | 从文档中提取的演员和实体提及 |
| `policy_positions` | 提取的演员政策立场 |
| `claim_conflicts` | 主张对比主张的矛盾记录 |
| `outlet_clusters` | k-means和层次聚类分配 |
| `outlet_scores` | 每周透明度评分（多样性、归因、中立性） |
配置的知识图谱存储在命名空间表（和可选的附加DuckDB数据库）中，因此新领域永远不会与新闻语料库冲突。
---
## 模型基准（启发式基线）
| 模型 | F1 | 备注 |
|---|---|---|
| ClaimDetector | 0.8645 | 二进制；博客和记录是最弱的源类型 |
| StanceClassifier | 0.4506 宏观 | 中立类别主导；少数派立场表现不佳 |
| FrameClassifier | 0.5200 宏观 | 政治框架召回率在启发式模式下接近零 |
参见[docs/model_benchmarks.md](docs/model_benchmarks.md)获取按源类型、长度和每类指标划分的完整分解。 当训练的检查点不存在时，管道会回落到关键词启发式并仍然返回有效预测。
---
## 文档
- [文档索引](docs/index.md)：按主题划分的完整文档地图
- [生成式UI](docs/genui.md)：画布、规划器、自适应性、ui-spec-v1
- [MCP重构计划](docs/architecture/MCP_REARCHITECTURE_PLAN.md)：能力平面和代理配置的知识图
- [项目结构](docs/PROJECT_STRUCTURE.md)
- [模型基准](docs/model_benchmarks.md)
- [Exactly-once delivery design](docs/EXACTLY_ONCE_DESIGN.md)
---
## 路线图
第一至六阶段（爬取和摄取；NLP、情感和知识图；事件检测和总结；仪表板和REST API；论点挖掘管道；出口分析）已经完成。
- **第7阶段，完全生成的自适应UI.** 完成。 固定视图被意图规划的画布（`ui-spec-v1`，启发式和可选的LLM规划器，带有实时计划预览的命令栏，根据使用信号自适应）取代。
- **第8阶段，MCP作为能力平面.** 完成。 目录来自发现，基于MCP的面板数据，Noesis作为MCP服务器，以及数据科学分析工具。
- **第9阶段，代理配置的知识.** 完成。 命名空间知识图的多个租户配置，具有自己的存储和管道，以及驱动它们的审计代理主机。
- **第10阶段，超越新闻.** 完成。 研究领域包，金融和法律领域通过配置建立，OSINT调查表面在证据纪律下。
- **即将推出.** 训练有素的模型检查点；跨数据集泛化（FEVER，LIAR，AVeriTeC）；预测分析；默认情况下启用实时面板数据。
---
## 联系和贡献
- GitHub Issues：错误报告和功能请求
- Pull Requests：欢迎贡献
- 邮箱：ikey168@proton.me
- 许可证：MIT
