Skip to content

docs: refresh public README #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lusblead merged 1 commit into from
Aug 3, 2026
+205 −102
Merged

docs: refresh public README #12

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
307 changes: 205 additions & 102 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,147 +1,250 @@
# Visualized Exp
<div align="center">
<p><strong>VISUALIZED EXP</strong></p>
<h1>把复杂问题，展开成可以继续走下去的知识空间</h1>
<p>
一款本地优先的 AI 可视化解释工具。<br />
看清概念关系，沿节点逐层探索，随时选中内容继续追问。
</p>

<p>
<a href="https://github.com/lusblead/Visual-Exp/actions/workflows/ci.yml"><img src="https://github.com/lusblead/Visual-Exp/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
<img src="https://img.shields.io/badge/version-0.2.0-6C63FF" alt="Version 0.2.0" />
<img src="https://img.shields.io/badge/Node.js-%E2%89%A522.13.0-339933?logo=nodedotjs&amp;logoColor=white" alt="Node.js 22.13.0 or newer" />
<img src="https://img.shields.io/badge/platform-Windows-0078D4?logo=windows11&amp;logoColor=white" alt="Windows" />
<a href="LICENSE"><img src="https://img.shields.io/github/license/lusblead/Visual-Exp?color=6C63FF" alt="MIT License" /></a>
</p>

<p>
<a href="#quick-start"><strong>快速开始</strong></a>
·
<a href="#first-use"><strong>首次配置</strong></a>
·
<a href="#user-guide"><strong>使用指南</strong></a>
·
<a href="https://github.com/lusblead/Visual-Exp/issues"><strong>反馈问题</strong></a>
</p>
</div>

---

## 不再被一篇长回答困住

普通 AI 回答把所有信息一次性铺在你面前。Visualized Exp 先呈现当前层最重要的概念和关系，再由你决定下一步往哪里走。

<table>
<tr>
<td align="center" width="33%">
<strong>01 · 提出问题</strong><br />
<sub>输入想真正弄懂的复杂主题</sub>
</td>
<td align="center" width="33%">
<strong>02 · 看清结构</strong><br />
<sub>先获得概念总览与当前层解释</sub>
</td>
<td align="center" width="33%">
<strong>03 · 自由深入</strong><br />
<sub>进入节点、解释术语或选区追问</sub>
</td>
</tr>
</table>

## ✨ 你可以这样探索

<table>
<tr>
<td width="50%" valign="top">
<strong>🧭 递归语义缩放</strong><br /><br />
每次只聚焦当前层。点击感兴趣的节点进入下一层，不必在一张无限扩张的知识图里迷路。
</td>
<td width="50%" valign="top">
<strong>🕸️ 可缩放概念总览</strong><br /><br />
先看核心概念和它们的联系，再阅读正文；需要时可以打开大图查看关系。
</td>
</tr>
<tr>
<td width="50%" valign="top">
<strong>💬 选中内容继续追问</strong><br /><br />
选中一句话，直接“向 AI 提问”，或让系统围绕这段内容继续“深入”。
</td>
<td width="50%" valign="top">
<strong>🔎 语境化术语解释</strong><br /><br />
单击正文中标出的术语查看说明，双击则进入更完整的深入解释。
</td>
</tr>
<tr>
<td width="50%" valign="top">
<strong>🌐 按需联网</strong><br /><br />
主问题和每轮选区对话分别控制是否搜索；配置搜索服务不会自动把所有问题送去联网。
</td>
<td width="50%" valign="top">
<strong>💾 本地知识记录</strong><br /><br />
自动保存探索会话，随时恢复之前的内容，并可导出 Markdown 或 JSON。
</td>
</tr>
</table>

<a id="quick-start"></a>

## 🚀 快速开始

> [!IMPORTANT]
> 完整的一键本地体验目前面向 Windows，因为 API Key 会通过 Windows 凭据管理器保存在当前电脑上。

### 环境要求

| Node.js | Java | Maven | .NET SDK |
| :---: | :---: | :---: | :---: |
| 22.13.0+ | 17+ | 3.6.3+ | 10.0+ |

### 安装并启动

把复杂问题展开成一个可以阅读、追问和继续深入的 AI 可视化解释空间。
```powershell
git clone https://github.com/lusblead/Visual-Exp.git
cd Visual-Exp
npm install
npm run dev:local
```

Visualized Exp 不把回答一次性压成长文或固定模板。它先生成当前层的解释与概念关系，只预备下一层入口；用户可以沿节点递归探索，也可以选中一句话直接向 AI 提问或继续深入。
启动完成后，打开 [http://localhost:3000](http://localhost:3000)。按 `Ctrl+C` 可以停止本次启动的所有本地服务。

![Visualized Exp 的离线演示：可缩放概念总览与递归阅读界面](docs/assets/product-overview.png)
<details>
<summary><strong>没有 API Key？先打开演示模式</strong></summary>

```mermaid
flowchart LR
Q["复杂问题"] --> O["当前层概念总览"]
O --> R["完整解释"]
R --> N["点击节点进入下一层"]
R --> S["选中句子"]
S --> A["向 AI 提问"]
S --> D["深入解释"]
A -. "按本轮设置" .-> W["受控联网搜索"]
```powershell
npm install
$env:EXPLANATION_MODEL_PROVIDER = "demo"
npm run dev
```

## 核心体验
演示模式不会调用真实模型，也不会启动完整本地后端，因此不包含持久化知识记录和选区 AI 对话。

- 递归语义缩放：根场景只展示 3–6 个高层入口，点击节点进入下一层，并用 `‹ / ›` 沿探索历史移动。
- 概念先行：开头用 Mermaid 绘制当前层概念关系；可打开大图并在 100%–300% 之间缩放。
- 渐进生成：只预生成当前入口的直接子场景，避免提前铺开整张知识图谱。
- 选区双入口：选中正文后可选择“向 AI 提问”或“深入”；左侧对话栏按需打开且可以关闭。
- 语境化名词解释：仅 AI 标注的名词可点击，解释不会修改主语义文档。
- 历史会话：Java 后端持久化知识会话和选区对话，支持刷新恢复、切换与删除。
- 可选联网：主问题提供开/关；选区对话每轮可选关闭、自动或强制。搜索服务已配置不等于已经允许联网。
- 离线演示：没有模型密钥时仍可使用确定性的演示生成器体验主要浏览流程。
</details>

## 模型、协议与搜索服务
<a id="first-use"></a>

“供应商预设”只是可编辑的默认值，不是项目分别实现了每家厂商的私有协议。当前 Java 模型通道实现两种协议：
## ⚙️ 首次配置

| 类型 | 当前实现 |
| --- | --- |
| 模型协议 | OpenAI Chat Completions、Anthropic Messages |
| 模型预设 | OpenAI、Anthropic、DeepSeek、Kimi、GLM、Gemini、通义千问、OpenRouter |
| 自定义模型 | 可配置 Base URL/完整请求 URL、模型 ID、协议和受限认证 Header |
| 搜索适配器 | Tavily Search、Brave Search |

Tavily 当前只用于搜索（Search），未接入 Extract、Crawl、Map 或 Research。搜索 API Key 属于搜索供应商鉴权，与模型 API Key 相互独立；`web_search` 工具本身并不天然要求某一家供应商或某一种 Key。

语义图生成默认通过本机 DeepSeek companion 使用项目定义的 Pro/Flash 模型路由。选区对话在没有启用模型覆盖时复用该通道；只有用户明确保存并启用模型覆盖后，新对话才改用 Java 中的供应商配置，无需重复配置同一把 DeepSeek Key。

## 系统结构

```mermaid
flowchart LR
B["浏览器"] -->|"同源请求"| V["Vinext / TypeScript BFF"]
V --> L["语义图生成与校验"]
V -->|"HttpOnly owner cookie"| J["Java 17 / Spring Boot"]
J --> H["H2 或 PostgreSQL"]
J --> M["模型供应商"]
J --> S["SearchProvider SPI"]
S --> T["Tavily Search"]
S --> R["Brave Search"]
V -->|"仅回环地址"| C["Windows .NET companion"]
C --> D["Windows Credential Manager"]
```
打开页面后，点击问题输入框右侧的设置按钮。

关键边界：
### 1. 连接默认 AI 服务

- 语义文档是知识结构的唯一事实来源；节点保存内容、层级、关系和展示建议，不保存像素坐标或 React 组件名。
- 模型只提交受验证的语义操作或受限的 `web_search(query, freshness?)` 调用，不能指定搜索请求 URL。
- 供应商 Key 只写不回显。Windows companion 将默认 DeepSeek Key 保存在系统凭据管理器；Java 使用 AES-256-GCM 加密模型覆盖和搜索供应商 Key。
- Java 对话提交使用稳定的 `clientTurnId`，持久化 `PENDING / COMPLETED / FAILED / UNKNOWN` 状态，无法确认结果时不会盲目重放付费请求。
在“AI 服务”中填写 DeepSeek API Key，然后点击“保存到本机”。这个服务负责生成可视化解释和深入说明，也会作为选区 AI 对话的默认模型。

更多设计细节见 [最小视觉对话规范](specs/minimal-visual-conversation.md)、[会话与凭据边界](specs/conversation-source-and-credentials.md)和 [Java 后端说明](backend/README.md)。
> [!NOTE]
> 保存模型或搜索配置时会执行一次最小验证请求，可能产生少量供应商用量。

## 环境要求
### 2. 可选：更换选区对话模型

完整的 `dev:local` 本地体验目前面向 Windows，因为它依赖 Windows Credential Manager。
如果希望“向 AI 提问”使用其他模型，可在“模型覆盖（可选）”中添加并启用配置。模型覆盖只影响之后新建的选区 AI 对话，不会替换默认的可视化解释服务。

| 依赖 | 最低版本 |
| 模型预设 | 支持方式 |
| --- | --- |
| Node.js | 22.13.0 |
| Java | 17 |
| Maven | 3.6.3 |
| .NET SDK | 10.0 |
| OpenAI、DeepSeek、Kimi、GLM、Gemini、通义千问、OpenRouter | OpenAI Chat Completions 兼容接口 |
| Anthropic | Anthropic Messages 接口 |
| 自主设置 | 自定义地址、模型 ID 与认证方式 |

## 快速开始
### 3. 可选：连接联网搜索

安装依赖并启动 companion、Java 后端和网站：
在“搜索服务”中配置 **Tavily** 或 **Brave Search**，并将它设为当前搜索服务。

```powershell
npm install
npm run dev:local
```
- 主问题：开启“允许下一次主问题联网”。
- 选区对话：发送前为本轮选择“关闭”“自动”或“强制”。

仅保存搜索服务不会自动联网；是否联网仍由对应入口的开关决定。

默认访问 `http://localhost:3000`。首次使用时打开右侧设置：
<a id="user-guide"></a>

1. 在上方保存 DeepSeek Key，用于语义图和默认选区对话。
2. 如有需要，在“模型覆盖”中配置其他模型供应商。
3. 如需联网，配置并启用搜索供应商，再在搜索服务区域允许下一次主问题联网；选区对话仍按每轮单独选择。
## 🧩 30 秒使用指南

保存模型或搜索配置会发起一次最小验证请求，可能计入供应商用量。
| 目标 | 操作 |
| --- | --- |
| 创建解释 | 在顶部输入问题，按回车或点击 `↑` |
| 进入下一层 | 点击正文区块或区块右侧的 `→` |
| 前进或返回 | 使用页面左上角的 `‹` 和 `›` |
| 查看术语说明 | 单击正文中带标记的术语 |
| 深入理解术语 | 双击带标记的术语 |
| 追问一句话 | 选中正文，点击“向 AI 提问” |
| 深入选中内容 | 选中正文，点击“深入” |
| 恢复知识记录 | 打开右上角的知识记录面板并选择会话 |
| 导出当前内容 | 在知识记录面板选择 Markdown 或 JSON |

只体验不调用真实模型的前端演示：
### 选择适合你的预生成方式

```powershell
$env:EXPLANATION_MODEL_PROVIDER = "demo"
npm run dev
```
| 模式 | 适合场景 | 模型用量 |
| --- | --- | :---: |
| **省流** | 只在点击后生成下一层 | 较少 |
| **平衡** | 提前准备少量可能访问的内容 | 适中 |
| **深入** | 准备更多下一层内容，减少后续等待 | 较多 |

## 🔐 数据与 API Key

该模式不会自动启动 Java 后端，因此不包含持久化历史和选区对话。手动拆分进程、PostgreSQL 配置及服务端环境变量见 [backend/README.md](backend/README.md) 和 [.env.example](.env.example)。任何密钥都不得使用 `NEXT_PUBLIC_` 前缀。
- 完整本地模式会把知识记录保存在当前电脑上。
- 默认 DeepSeek Key 保存在 Windows 凭据管理器中，不需要写入项目文件。
- 模型和搜索服务的 Key 保存后不会在页面中回显。
- 不要把 API Key 写入代码、提交到 Git，或添加到任何以 `NEXT_PUBLIC_` 开头的变量中。

## 验证
<details>
<summary><strong>端口被占用</strong></summary>

完整的本地发布门禁：
可以为网页和后端指定其他端口：

```powershell
npm run harness:minimal
$env:PORT = "3001"
$env:BACKEND_PORT = "18080"
npm run dev:local
```

该命令会依次运行 companion 构建、Java 测试、前端构建、Node 测试、TypeScript 类型检查和 ESLint。也可以单独运行：
然后访问 [http://localhost:3001](http://localhost:3001)。

</details>

<details>
<summary><strong><code>npm run dev:local</code> 启动失败</strong></summary>

先确认依赖都可以从终端执行：

```powershell
npm test
npm run typecheck
npm run lint
node --version
java -version
mvn -version
dotnet --version
```

自动化测试不需要真实 API Key，也不应发起真实模型或搜索请求。
如果某条命令不存在，请安装对应依赖并重新打开终端。首次启动还需要能够访问 npm、Maven 和 NuGet 的依赖下载服务。

</details>

<details>
<summary><strong>页面可以打开，但无法生成真实解释</strong></summary>

## 安全与部署边界
- 确认不是以 `demo` 模式启动。
- 打开设置，确认 DeepSeek Key 已验证并保存。
- 如果刚替换 Key，请重新提交问题。

本项目当前是本地优先、单用户应用。HttpOnly owner cookie 只用于同一设备上的数据隔离，不是账号登录、强身份认证或多设备同步方案。
</details>

不要把当前本地配置直接当作公开多用户生产服务。公开部署前至少需要补齐：
<details>
<summary><strong>已经配置搜索服务，但回答没有联网</strong></summary>

- 真实的身份认证、授权与租户隔离；
- 请求速率限制、并发上限、配额和费用预算；
- HTTPS、服务端 Secret Manager 和密钥轮换；
- 数据库备份、迁移与恢复演练；
- 出站网络防火墙或代理、审计日志和运行监控。
请同时确认：

请勿提交 `.env`、API Key、Token、数据库文件、日志、个人会话或包含这些内容的截图。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。
- Tavily 或 Brave Search 已验证并设为当前服务；
- 主问题的“允许下一次主问题联网”已开启，或选区对话本轮选择了“自动”或“强制”。

## 参与贡献
</details>

## 🤝 参与项目

| | |
| --- | --- |
| 🧾 [查看版本记录](CHANGELOG.md) | 🛠️ [阅读贡献指南](CONTRIBUTING.md) |
| 🐞 [提交问题](https://github.com/lusblead/Visual-Exp/issues) | 🔒 [私下报告安全问题](SECURITY.md) |

提交代码前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并运行完整门禁。行为变更还应同步更新 `docs/feature-flows/` 中对应的流程与可追溯信息。
Visualized Exp 当前定位为本地优先、单用户应用，暂不提供可直接公开运营的多用户 SaaS 部署方案。

## 版本与许可证
---

- 版本记录：[CHANGELOG.md](CHANGELOG.md)
- 许可证：[MIT](LICENSE)
<div align="center">
<p>如果 Visualized Exp 对你有帮助，欢迎点一个 Star 或分享你的使用反馈。</p>
<p><sub>Local-first · Single-user · MIT License</sub></p>
</div>
Loading