内容
# 辩证法 由 TACITUS 提供
### TACITUS 神经符号栈的推理核心，用于冲突智能。
[](https://github.com/sargonxg/A2_DIALECTICAbyTACITUS/actions)
[](LICENSE)
[](#状态与参与方式)
[](https://python.org)
[](https://neo4j.com/cloud/aura/)
> ⚠️ **实验性作品，持续进行中。** 实时MVP，积极开发中，可能存在破坏性变更。
> 由 [TACITUS](https://www.tacitus.me) 在开放环境中构建。 **欢迎反馈、问题和PR** — 请参阅 [状态与参与方式](#状态与参与方式)。
> *"我们使冲突可计算，以便人类做出更好的判断。"*
辩证法将任何冲突 — 从工作场所纠纷到地缘政治战争 — 构建成一个可计算的知识图谱，基于30多个学术框架。它是TACITUS栈的指挥核心，也是 [praxis.tacitus.me](https://praxis.tacitus.me) 的 backbone。
---
## TACITUS 三位一体
辩证法并非独立存在。它是三项服务的推理核心，每项服务可独立发布；共同覆盖完整的神经符号表面。
| 仓库 | 角色 | 语言 | 拥有 |
|---|---|---|---|
| **辩证法** （此仓库） | 推理核心 + 指挥 | Python | 冲突语法本体，Neo4j图谱，6个代理，GraphRAG，FastAPI，MCP服务器 |
| [**AGON**](https://github.com/sargonxg/AGON) | 证据引擎 | Rust | 声明验证，矛盾，摩擦图谱，确定性推理 |
| [**KAIROS**](https://github.com/sargonxg/KAIROS-temporal-vision-TACITUS) | 时间引擎 | Rust | 日期提取，Allen-13关系，承诺状态，事件边界 |
```mermaid
flowchart LR
SRC[原始文本 / 档案] --> K[KAIROS<br/>时间支架]
K --> D[DIALECTICA<br/>本体 + 推理]
D --> A[AGON<br/>证据验证]
A --> G[(Neo4j<br/>冲突语法图谱)]
G --> PR[praxis.tacitus.me<br/>+ MCP + SDK + API]
```
**为什么拆分：** Rust用于边缘的确定性和快速结构工作。Python用于中间的编排和LLM推理。 **为什么结合：** 每个仓库都填补了其他仓库无法填补的空白 — 时间丰富性（KAIROS），证据基础的声明（AGON），本体和推理（辩证法）。
📖 **集成文档：** [`docs/integration/`](docs/integration/) — 架构，合约，本体映射，路线图，PRAXIS backbone。
---
## 您将获得
- **冲突语法本体** — 15个节点类型，20个边类型，25+受控词汇，6个子域（地缘政治，工作场所，商业，法律，武装，环境）
- **25+确定性符号规则** — Glasl升级，Zartman成熟度，Mayer信任，French/Raven权力，因果链
- **6个AI代理** — 分析师，顾问，比较器，预测器，调解员，理论家
- **GraphRAG检索** — 混合向量 + 图谱 + 时间 + 互惠排名融合
- **15个理论框架** — Fisher/Ury，Thomas-Kilmann，Glasl，Galtung，Lederach等
- **LangGraph提取管道** — 10步DAG，Gemini 2.5 Flash + 可选GLiNER NER
- **多数据库** — Neo4j Aura（主要），FalkorDB，Spanner
- **TACITUS集成API** — `/v1/integration/*` 用于其他TACITUS应用程序（PRAXIS，Trust Graph，Wind Tunnel）
- **MCP服务器** — 5个工具用于Claude Desktop（即将增加到9个）
- **实时摄入** — Project Gutenberg + 上传 + 粘贴，带有SSE进度 + 自动推理
- **630+测试** 跨4个Python包
---
## 快速开始
```bash
git clone https://github.com/sargonxg/A2_DIALECTICAbyTACITUS.git
cd A2_DIALECTICAbyTACITUS
cp .env.example .env
# 启动Neo4j + Redis + API
make dev-local
# 种子6个冲突场景（114个节点，126个边）
make seed
# 验证
curl http://localhost:8080/health
curl -H "X-API-Key: dev-admin-key-local" http://localhost:8080/v1/workspaces
```
| 服务 | URL |
|---|---|
| API | http://localhost:8080 （Swagger位于 `/docs`） |
| Neo4j浏览器 | http://localhost:7474 （`neo4j` / `dialectica-dev`） |
| 前端 | `cd apps/web && npm install && npm run dev` → http://localhost:3000 |
**参见 [`docs/local-development.md`](docs/local-development.md) 了解非Docker设置，CLI用法和可选的图推理子系统。**
---
## 架构（DIALECTICA内部）
辩证法的四层神经符号栈：
```mermaid
graph TB
subgraph "第1层：神经摄入"
A[原始文本] --> B[GLiNER预过滤]
B --> C[Gemini Flash提取器]
C --> D[Pydantic验证]
end
subgraph "第2层：符号表示"
D --> E[冲突语法<br/>15个节点 / 20个边]
E --> F[(Neo4j Aura)]
E --> G[25+词汇]
end
subgraph "第3层：推理和推断"
F --> H[GraphRAG检索器]
F --> I[符号规则引擎]
H --> J[上下文构建器]
I --> K[Glasl / Zartman / 信任]
J --> L[Gemini Pro综合]
K --> L
end
subgraph "第4层：决策支持"
L --> M[6个AI代理]
M --> N[人类决策者]
N -->|验证循环| F
end
```
**关键不变性：** 确定性符号结论永远不会被概率神经预测覆盖。通过 `confidence_type` 标签强制执行。
📖 **深度架构：** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
📖 **神经符号原理：** [`docs/neurosymbolic-rationale.md`](docs/neurosymbolic-rationale.md)
📖 **三位一体集成架构：** [`docs/integration/ARCHITECTURE.md`](docs/integration/ARCHITECTURE.md)
---
## API表面
| 组 | 端点模式 | 目的 |
|---|---|---|
| 健康 | `/health`, `/health/live`, `/health/ready` | 探针 |
| 工作空间 | `/v1/workspaces` | CRUD |
| 摄入 | `/v1/workspaces/{id}/ingest/*`, `/v1/gutenberg/catalog` | 文档摄入 + Gutenberg语料库 |
| 提取 | `/v1/workspaces/{id}/extract`, `/extractions/{id}/stream` (SSE) | 管道 + 进度 |
| 图谱 | `/v1/workspaces/{id}/graph`, `/graph/subgraph` | 读取图谱 |
| 推理 | `/v1/workspaces/{id}/analyze`, `/reasoning` | 符号 + 代理推理 |
| 理论 | `/v1/theory/frameworks`, `/v1/theory/match` | 15个框架 |
| **集成** | `/v1/integration/graph`, `/context`, `/query` | **用于其他TACITUS产品（PRAXIS，Trust Graph）** |
| 管理 | `/v1/admin/*` | 基准测试，用量，系统信息 |
**随三位一体连接而来：**
- `/v1/temporal/*` — 代理KAIROS供外部开发者使用
- `/v1/evidence/*` — 代理AGON
📖 **API参考：** [`docs/api-reference.md`](docs/api-reference.md)
📖 **SDK快速入门：** [`docs/sdk-quickstart.md`](docs/sdk-quickstart.md)
---
## 部署
一键云运行部署：
```bash
# 在秘密管理器中存储Neo4j Aura凭证
make setup-secrets
# 部署
bash infrastructure/scripts/deploy-cloudrun.sh YOUR_GCP_PROJECT_ID us-central1
# 前端
cd apps/web && vercel --prod
```
📖 **完整部署指南：** [`docs/deployment.md`](docs/deployment.md)
📖 **生产运行手册：** [`docs/runbook.md`](docs/runbook.md)
📖 **GCP成本和清理：** [`docs/GCP_COST_CLEANUP.md`](docs/GCP_COST_CLEANUP.md)
---
## 仓库布局（高级别）
```
A2_DIALECTICAbyTACITUS/
├── packages/
│ ├── ontology/ # 冲突语法（15个节点，20个边，25+词汇，15个理论，25+符号规则）
│ ├── graph/ # 数据库抽象（Neo4j，FalkorDB，Spanner）
│ ├── extraction/ # LangGraph管道 + Gemini + GLiNER + 源加载器
│ ├── reasoning/ # GraphRAG + 符号规则引擎 + 6个代理 + KGE
│ ├── api/ # FastAPI（14个路由器，身份验证，多租户）
│ ├── mcp/ # MCP服务器用于Claude Desktop（今天有5个工具，将来有9个）
│ ├── sdk-typescript/ # @tacitus/dialectica-sdk
│ └── integrations/ # [计划] KAIROS + AGON客户端（参见docs/integration/）
├── apps/web/ # Next.js 15前端
├── infrastructure/ # Terraform + 部署脚本
├── data/seed/ # 6个样本冲突 + 基准测试语料库
└── docs/
├── integration/ # ★ 三位一体集成文档（架构，合约，映射，路线图）
├── ARCHITECTURE.md
├── api-reference.md
├── deployment.md
└── ...
```
---
## 测试
```bash
make test # 所有Python测试（630+）
make test-ontology # 452个测试，82%覆盖率
make test-api # 72个测试
make test-extraction # 75个测试
make test-reasoning # 29个测试
make test-e2e # Playwright（前端运行中）
make quality-all # lint + 类型检查 + tsc + web-lint
```
📖 **基准测试：** [`docs/benchmarking.md`](docs/benchmarking.md) — 4个金标准语料库（JCPOA，Romeo/Juliet，Crime/Punishment，War/Peace），35+基准问题
---
## MCP服务器（Claude Desktop）
今天：5个工具 — `query_conflict_graph`, `get_actor_analysis`, `get_escalation_status`, `compare_conflicts`, `ingest_document`.
三位一体连接后（计划中）：+4个工具 — `temporal_query`（KAIROS），`verify_claim`（AGON），`find_contradictions`（AGON），`commitment_state`（KAIROS）。
📖 **设置：** [`docs/mcp-setup.md`](docs/mcp-setup.md)
---
## 技术栈
| 层 | 技术 |
|---|---|
| 语言 | Python 3.12+，TypeScript |
| 包管理器 | UV（Python），npm（TS） |
| API | FastAPI，异步，OpenAPI |
| 图谱数据库 | Neo4j Aura（主要），FalkorDB，Spanner |
| 向量 | Qdrant（768d + 256d命名向量） |
| LLM | Gemini 2.5 Flash + Pro（Vertex AI） |
| NER（可选） | GLiNER |
| 管道 | LangGraph（10步DAG） |
| 前端 | Next.js 15，React 19，Tailwind，D3.js |
| 部署 | Cloud Run + Vercel |
| CI/CD | GitHub Actions，Cloud Build |
| 分析 | BigQuery（可选） |
| 高级ML | Databricks（可选，用于KGE训练） |
---
## 诚实的性能
辩证法今天做得好的事情：
- 从文本中结构化提取参与者、事件、冲突、承诺
- 图谱上的确定性推理（升级阶段、成熟度、信任分析）
- 具有审计账本的多租户API
- 多数据库后端
它今天不做的事情：
- 它不产生判决。它产生结构化的情报。
- 单个文档聚焦于每个摄入作业的冲突推理是工作区级别的，而不是自动的。
- 声明验证目前通过Gemini进行最佳努力。确定性验证随着AGON连接而来（参见 [`docs/integration/`](docs/integration/)）。
- 时间推理基于时间戳，不是Allen区间。随着KAIROS连接而来。
如果这些对您的用例很重要，请遵循集成路线图。
---
## 状态与参与方式
辩证法是 **实验性作品，持续进行中**。实时系统运行，测试通过，部署发布 — 但API表面、本体和集成合约仍在演化中。将代码库视为一个严肃的原型，而不是一个稳定的产品。
**欢迎评论 — 优先渠道：**
- 💬 **[GitHub讨论](https://github.com/sargonxg/A2_DIALECTICAbyTACITUS/discussions)** — 想法、问题、接下来要构建什么
- 🐛 **[问题](https://github.com/sargonxg/A2_DIALECTICAbyTACITUS/issues)** — 错误、具体提案
- 📬 **[tacitus.me](https://www.tacitus.me)** — 直接联系或合作对话
- 🔀 **PRs** — 欢迎审查；请在 [`docs/integration/`](docs/integration/) 中触及集成合约，然后进行大型更改
如果您正在尝试使用真实数据，我真诚地想听听有什么问题，有什么惊喜。
## 贡献
```bash
git checkout -b feat/your-feature
# 惯例提交：feat:, fix:, refactor:, docs:, test:, infra:
make quality-all # 必须通过
```
📖 参见 [`CHANGELOG.md`](CHANGELOG.md) 获取发布历史。
---
## 许可证
Apache 2.0 — 参见 [LICENSE](LICENSE).
---
## TACITUS
用于机构的工具，帮助他们在压力下做出更清晰的判断。 [tacitus.me](https://www.tacitus.me).
```text
辩证法 — 推理核心
AGON — 证据引擎
KAIROS — 时间引擎
PRAXIS — 冲突智能SaaS（驾驶舱）
CONCORDIA — 语音优先的冲突调解
```
*使冲突可计算，以便人类做出更好的判断。*
