# logic-lens

**Repository Path**: powercs12/logic-lens

## Basic Information

- **Project Name**: logic-lens
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-21
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LogicLens

LogicLens 是**论证与因果关系的结构化基础设施**（Schema Runtime + Canvas）：  
把判断变成 AI 可读写、人可检查的因果账本；**真正“聪明”的推理交给外接 AI**。

> **定位（B 路线 · 硬基建）**  
> 图是唯一真相源（Source of Truth）。AI 通过协议读图、提补丁、写回结构；聊天输出必须能引用节点/边 ID。  
> LogicLens **不做**最聪明的内置大脑，**做** AI 时代的「论证复式记账本」。

## 产品北极星

| 维度 | 说明 |
|------|------|
| **我们是** | 因果/论证的 Canonical Schema、可视化编辑运行时、AI 读写协议、可追溯导入导出 |
| **我们不是** | 通用聊天机器人、纯展示知识图谱玩具、协作社交网络 |
| **人看什么** | 画布上的节点、边、证据、假设、置信度与版本 |
| **AI 干什么** | 抽取、审计、证伪、写作、推演——通过 Tool/API 操作同一套账本 |
| **成功标准** | 同一张图可被人编辑、被任意模型协议读写、产出可引用结构的内容，并跨读/写/学/决策复用 |

### 四条 workload（同一账本，不是四个产品）

1. **读文章/论文**：拆别人论证是否靠谱  
2. **写东西**：让自己的论证过关并导出成稿  
3. **学经济学**：把模型/政策机制想透  
4. **做决策**：投资/职业/策略压力测试  

差异只在意图模板、检查清单与导出格式；底层数据结构与 AI 协议统一。

### 能力边界

| LogicLens 自有（不外包） | 外接 AI 负责 |
|--------------------------|--------------|
| Canonical Graph Schema | 从文本/PDF 抽论证 |
| 校验与约束（类型、冲突、非法补丁拒绝） | 找漏洞、脆弱边、反事实话术 |
| 人可读 Canvas 编辑 | 论文段/决策备忘等高质内容 |
| AI Tool Protocol（读图 / patch / 校验） | 经济学机制解释与情景叙述 |
| 导入导出与引用式输出 | 可替换的模型供应商 |

详细改造路线见：`docs/changes/2026-07-18-14-53-00-硬基建定位与完整改造方案/`。

## 当前状态

- 前端：React 18 + Vite 6 + TypeScript + React Flow 12 + Zustand 5 + Ant Design 6 + Tailwind CSS
- 后端：Node.js + Express 4 + TypeScript
- 数据库：MySQL（项目数据 + 用户认证）
- 认证：JWT（Access Token + Refresh Token 轮换）
- 测试：Vitest（单元测试）+ Playwright（E2E 测试）
- 运行模式：登录云端模式 + 游客本地模式（无 token 时默认进入游客模式）
- 包管理：前端 pnpm / 后端 npm

## 功能范围

### 画布核心
- 关系画布：节点、连线、属性编辑、自动布局、快捷键
- 画布内节点搜索（Cmd+F / Ctrl+F）：模糊匹配 + 平滑定位 + 金色闪烁
- 多选节点与批量操作：套索框选、Shift+单击追加、批量删除/改类型/对齐/等距分布
- 节点分组与子图折叠：选中节点创建分组、折叠/展开切换、连线自动重路由
- AI 实时逻辑一致性 lint：自动检测冲突边、矛盾路径、孤立节点、不连通子图
- 反驳/前提/根据节点：支持 rebuts/supports 连线类型和 premise/warrant 节点类型

### 分析与模拟
- 逻辑探针：AI 流式分析 + 历史记录（云端/本地）
- 教练模式：苏格拉底式 AI 追问
- 对战模式：正反方双栏画布 + AI 联合审计
- 沙箱模拟：外生变量输入、公式推演、实时结果更新
- 蒙特卡洛模拟：概率分布输入、Web Worker 批量运行、统计直方图
- 场景管理器：多组参数保存/切换、场景差异对比
- 假设检验沙盒：反事实压力测试、边关键度排序
- 循环因果/反馈回路可视化

### 证据系统
- 连线证据 S/A/B/C 四级评级
- 论证质量仪表盘：整图逻辑支撑强度评分 + 证据质量 Tab
- 核验工作台：集中筛选、风险排序、逐条核验
- 联网搜索：AI 检索公开资料、来源一致性比对、链接可达性校验
- 来源可信度自动分级（高/低/未知）
- 贝叶斯动态置信度更新

### 协作与社区
- 多项目管理：新建、切换、重命名、删除、导入导出
- 画布多人协同（首版）：协作者管理 + 共享编辑 + 版本冲突提示 + 手动同步
- 功能进度协作提案：提案发布 + 协作参与
- 案例图书馆：内置案例 + 社区投稿 / 收藏 / Fork
- 社区共识地图：多图谱聚合、高频节点与关系提取
- 利益相关者标注层：受益方/受损方/中立方

### AI 系统
- AI 模型管理：多供应商配置（DeepSeek / OpenAI / 智谱 / MiniMax / 月之暗面等）、自定义供应商、模型参数、连通性测试、真实调用监控
- AI 场景管理器：自定义提示词
- 图谱对话能力：自然语言编辑画布
- AI 增量导入 / 思维导图转因果图
- 外部 API 接口：REST API 创建画布项目、追加节点与连线

### 可视化
- 2D/3D 数据打通：双向同步
- 神经网络式节点裂变动画（BFS 扩散）
- JSON 属性注释联动弹框
- 图谱版本对比（节点/连线级 diff）
- 导出增强：Markdown 报告 / 静态 HTML 分享页

## 最近更新

- 思考内容与正文输出已做流式隔离，避免两者互相污染。
- 智谱（`zhipu`）流式解析按官方字段处理：
  - `choices[0].delta.content`：正文增量
  - `choices[0].delta.reasoning_content`：思考增量
  - `choices[0].finish_reason`：完成原因（末 chunk）
  - `usage`：令牌统计（末 chunk）
- MiniMax 等兼容场景新增 `<think>...</think>` 分离解析，思考文本不会混入正文。
- 思考区与正文区交互更新：
  - 思考阶段仅展示思考小块（实时显示最新三行），不展示正文内容
  - 思考阶段不展示正文进度条，进度不跳动
  - 思考结束后立即出现可折叠的“思考过程”面板，可在正文流式输出期间随时展开
  - 思考过程展开后使用 Markdown 渲染，正文保持 Markdown 实时渲染
- 点击“重新分析”会先清空旧思考与旧正文，再启动新一轮流式分析

### 2026-05 代码质量与安全全面优化
- **安全修复**：SSRF 防护（拒绝内网地址请求）、Body limit 5MB、Admin 守卫、全局限流 100req/min、Refresh Token 轮换
- **架构重构**：后端 index.ts 1496 行 → 115 行，路由提取到独立文件；前端 useStore.ts 拆分为 5 个独立 slice；Canvas.tsx 2165 行 → 1487 行
- **Bug 修复**：DebateCanvas 16 处 stale closure 修复；流式 AI 请求接入 AbortController；Network3D rAF 防空转

### 2026-05 AI 实时逻辑一致性 lint
- 每次连线变更后自动运行 4 项规则检查：冲突边、矛盾路径、孤立节点、不连通子图
- 右上角 lint 状态按钮 + 抽屉列表 + 定位按钮
- 6 条单元测试覆盖

### 2026-05 画布效率提升
- **画布内节点搜索**（Cmd+F / Ctrl+F）：模糊匹配、平滑定位、金色闪烁 1.5s
- **多选节点与批量操作**：套索框选、Shift+单击追加、批量删除/改类型/四方向对齐/纵向等距
- **节点分组与子图折叠**：创建即折叠、蓝色虚框容器、外部连线自动重路由；展开时恢复原位置；分组持久化到 localStorage

## 页面截图

### 主页

![主页截图](images/主页.png)

### 关系画布

![关系画布截图](images/画布.png)

### 导入画布

![导入画布截图](images/导入画布.png)

### 逻辑探针

![逻辑探针截图](images/逻辑探针.png)

### 案例图书馆

**内置案例**

![案例图书馆-内置案例截图](images/案例图书馆1-内置案例.png)

**社区案例**

![案例图书馆-社区案例截图](images/案例图书馆2-社区案例.png)

### 3D 关系网络

![3D关系网络截图](images/3D关系网络.png)

### 关系投稿到社区

![关系投稿到社区截图](images/关系投稿到社区.png)

### 压力测试

![压力测试截图](images/压力测试.png)

### 对战模式

![对战模式截图](images/对战模式.png)

### 教练模式

![教练模式截图](images/教练模式.png)

### AI 管理

![AI管理截图](images/AI管理.png)

### AI 场景

![AI场景截图](images/AI场景.png)

### 个人仪表盘

![个人仪表盘截图](images/个人仪表盘.png)

## 当前限制

- 画布协同为首版：提供“协作者共享编辑 + 更新检测同步”，未提供实时光标/评论/通知。
- 协作提案能力已上线首版（登录态可发布与参与），暂不含评论/通知等深度协同。
- 写作 workload 可生成引用式论证草稿；完整富文本编辑与第三方发布不在当前范围。
- 案例收藏、AI 场景提示词仅保存在浏览器本地，不支持云端同步。
- Dashboard 统计数据为手动快照，需运行 `python count_lines.py` 刷新。
- 接口自动化测试体系基础设施已落地（backend vitest + supertest，auth/projects 共 38 个集成用例），其余路由覆盖和 CI 阻断仍需继续补齐。

## 项目结构

- `frontend/src/`：前端源码
- `backend/src/`：后端源码
- `docs/`：业务/技术/运维文档
- `docs/diagrams/`：Mermaid 流程图
- `backend/supabase/`：历史迁移遗留目录（非当前运行依赖）

## 环境要求

- Node.js 18+
- pnpm 9+（前端推荐）
- npm（后端脚本使用 npm）
- MySQL 8.0+

## 快速启动

### 1. 安装依赖

```bash
# 前端依赖
cd frontend
pnpm install

# 后端依赖
cd ../backend
npm install
```

### 2. 初始化数据库

在 MySQL 中创建数据库后，执行 schema 初始化脚本：

```sql
CREATE DATABASE IF NOT EXISTS logic_lens CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

```bash
# 在项目根目录执行（示例）
mysql -u root -p logic_lens < backend/schema.sql
```

注意：`backend/schema.sql` 包含 `DROP TABLE IF EXISTS`，会重建核心表，请勿在未备份生产数据时直接执行。

### 3. 配置后端环境变量

创建 `backend/.env`：

```env
PORT=3001
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=logic_lens
JWT_SECRET=replace_with_a_strong_secret
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
AI_PROXY_REQUIRE_AUTH=false
```

`AI_PROXY_REQUIRE_AUTH=true` 时，后端 AI 代理要求有效登录态并写入调用审计；默认 `false` 保持本地游客模式可用。用户在 AI 设置页填写的第三方模型 API Key 仍保存在浏览器本地。

### 4. 启动服务

推荐在仓库根目录使用统一启动脚本。它会先等待后端健康检查通过，再启动前端；按 `Ctrl+C` 会同时停止两个服务：

```bash
pnpm dev
```

- 前端：`http://127.0.0.1:5173`
- 后端：`http://127.0.0.1:3001`
- API：`http://127.0.0.1:3001/api`

如需临时换端口，只设置统一入口变量，前端 API 地址会自动同步：

```bash
BACKEND_PORT=3101 FRONTEND_PORT=5180 pnpm dev
```

不要通过外层 `PORT` 或 `VITE_API_URL` 覆盖统一脚本；脚本会主动覆盖这两个变量，避免前后端端口漂移。自定义前端端口时，脚本也会把对应的 `localhost` / `127.0.0.1` 来源自动加入后端 CORS，并保留已有 `CORS_ORIGIN` 来源。

双终端启动仍保留用于单服务排障：

```bash
# 终端 A：后端排障
cd backend
npm run dev

# 终端 B：前端排障
cd frontend
pnpm dev
```

### 5. 配置前端 API 地址

单独启动前端时才需要在 `frontend/.env` 中配置：

```env
VITE_API_URL=http://localhost:3001/api
```

## API 快速索引

- 认证：`/api/auth/register`、`/api/auth/login`、`/api/auth/refresh`、`/api/auth/logout`、`/api/auth/me`
- 项目：`/api/projects`（GET/POST）和 `/api/projects/:id`（GET/PUT/DELETE）
- 项目协作：`/api/projects/:id/collaborators`（GET/POST）和 `/api/projects/:id/collaborators/:userId`（DELETE）
- 逻辑探针历史：`/api/logic-probes`、`/api/logic-probes/latest`、`/api/logic-probes/bulk`、`/api/logic-probes/clear`、`/api/logic-probes/:id`
- 功能进度协作：`/api/roadmap-collab/items`、`/api/roadmap-collab/items/:id/support`
- 功能进度管理：`/api/features`、`/api/features/:id`、`/api/features/:id/progress-logs`（写操作需管理员权限）
- 3D 图谱：`/api/network-3d/graphs`、`/api/network-3d/graphs/:id`
- 社区案例：`/api/community`、`/api/community/consensus`、`/api/community/:id/star`、`/api/community/:id/fork`
- 外部 API：`/api/external/keys`、`/api/external/canvases`、`/api/external/canvases/:id/nodes`、`/api/external/canvases/:id/edges`
- 图谱快照：`/api/snapshots`
- AI 代理：`/api/ai/chat/completions`、`/api/ai/web-search`、`/api/ai/check-urls`
- 文档读取：`/api/docs/change-requirement`
- 健康检查：`/api/health`

## 运维排障（最小清单）

- 401/403：检查 `Authorization: Bearer <token>` 和 `JWT_SECRET` 是否一致。
- 登录成功但项目为空：确认数据库已执行 `backend/schema.sql`，并检查 `projects` 表。
- 逻辑探针历史接口 500：确认服务启动时已成功创建 `logic_probe_histories` 表（后端会尝试自动创建）。
- AI 连通性测试失败：优先检查 API Key、Base URL 与模型 ID。
- MiniMax 报错 `1008/2049`：通常是环境与 Key 不匹配（中国区 `minimaxi.com` / 国际版 `minimax.io`），或 Key 类型不匹配（Coding Plan Key 与按量付费 API Key 不互通）。

## 文档入口

- 总览与对齐基线：`docs/版本对齐.md`
- 用户功能说明：`docs/功能指南.md`
- 协同操作说明：`docs/协同使用说明书.md`
- 项目与架构说明：`docs/项目文档.md`
- 运维计划与任务：`docs/迁移计划.md`、`docs/迁移任务.md`