From 3df580d0e630a00a6bc7d2da42bc7928b0e69f77 Mon Sep 17 00:00:00 2001 From: lusblead <187519937+lusblead@users.noreply.github.com> Date: Mon, 3 Aug 2026 10:18:56 +0800 Subject: [PATCH] docs: refresh public README --- README.md | 307 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 205 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 6957bda..cbac96d 100644 --- a/README.md +++ b/README.md @@ -1,147 +1,250 @@ -# Visualized Exp +
+

VISUALIZED EXP

+

把复杂问题，展开成可以继续走下去的知识空间

+

+ 一款本地优先的 AI 可视化解释工具。
+ 看清概念关系，沿节点逐层探索，随时选中内容继续追问。 +

+ +

+ CI + Version 0.2.0 + Node.js 22.13.0 or newer + Windows + MIT License +

+ +

+ 快速开始 + · + 首次配置 + · + 使用指南 + · + 反馈问题 +

+
+ +--- + +## 不再被一篇长回答困住 + +普通 AI 回答把所有信息一次性铺在你面前。Visualized Exp 先呈现当前层最重要的概念和关系，再由你决定下一步往哪里走。 + + + + + + + +
+ 01 · 提出问题
+ 输入想真正弄懂的复杂主题 + 		+ 02 · 看清结构
+ 先获得概念总览与当前层解释 + 		+ 03 · 自由深入
+ 进入节点、解释术语或选区追问 +
+ +## ✨ 你可以这样探索 + + + + + + + + + + + + + + +
+ 🧭 递归语义缩放

+ 每次只聚焦当前层。点击感兴趣的节点进入下一层，不必在一张无限扩张的知识图里迷路。 + 		+ 🕸️ 可缩放概念总览

+ 先看核心概念和它们的联系，再阅读正文；需要时可以打开大图查看关系。 +
+ 💬 选中内容继续追问

+ 选中一句话，直接“向 AI 提问”，或让系统围绕这段内容继续“深入”。 + 		+ 🔎 语境化术语解释

+ 单击正文中标出的术语查看说明，双击则进入更完整的深入解释。 +
+ 🌐 按需联网

+ 主问题和每轮选区对话分别控制是否搜索；配置搜索服务不会自动把所有问题送去联网。 + 		+ 💾 本地知识记录

+ 自动保存探索会话，随时恢复之前的内容，并可导出 Markdown 或 JSON。 +
+ + + +## 🚀 快速开始 + +> [!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) +
+没有 API Key？先打开演示模式 -```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 后端持久化知识会话和选区对话，支持刷新恢复、切换与删除。 -- 可选联网：主问题提供开/关；选区对话每轮可选关闭、自动或强制。搜索服务已配置不等于已经允许联网。 -- 离线演示：没有模型密钥时仍可使用确定性的演示生成器体验主要浏览流程。 +
-## 模型、协议与搜索服务 + -“供应商预设”只是可编辑的默认值，不是项目分别实现了每家厂商的私有协议。当前 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`。首次使用时打开右侧设置： + -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_` 开头的变量中。 -## 验证 +
+端口被占用 -完整的本地发布门禁： +可以为网页和后端指定其他端口： ```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)。 + +
+ +
+npm run dev:local 启动失败 + +先确认依赖都可以从终端执行： ```powershell -npm test -npm run typecheck -npm run lint +node --version +java -version +mvn -version +dotnet --version ``` -自动化测试不需要真实 API Key，也不应发起真实模型或搜索请求。 +如果某条命令不存在，请安装对应依赖并重新打开终端。首次启动还需要能够访问 npm、Maven 和 NuGet 的依赖下载服务。 + +
+ +
+页面可以打开，但无法生成真实解释 -## 安全与部署边界 +- 确认不是以 `demo` 模式启动。 +- 打开设置，确认 DeepSeek Key 已验证并保存。 +- 如果刚替换 Key，请重新提交问题。 -本项目当前是本地优先、单用户应用。HttpOnly owner cookie 只用于同一设备上的数据隔离，不是账号登录、强身份认证或多设备同步方案。 +
-不要把当前本地配置直接当作公开多用户生产服务。公开部署前至少需要补齐： +
+已经配置搜索服务，但回答没有联网 -- 真实的身份认证、授权与租户隔离； -- 请求速率限制、并发上限、配额和费用预算； -- HTTPS、服务端 Secret Manager 和密钥轮换； -- 数据库备份、迁移与恢复演练； -- 出站网络防火墙或代理、审计日志和运行监控。 +请同时确认： -请勿提交 `.env`、API Key、Token、数据库文件、日志、个人会话或包含这些内容的截图。安全问题请按 [SECURITY.md](SECURITY.md) 私下报告。 +- Tavily 或 Brave Search 已验证并设为当前服务； +- 主问题的“允许下一次主问题联网”已开启，或选区对话本轮选择了“自动”或“强制”。 -## 参与贡献 +
+ +## 🤝 参与项目 + +| | | +| --- | --- | +| 🧾 [查看版本记录](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) +
+

如果 Visualized Exp 对你有帮助，欢迎点一个 Star 或分享你的使用反馈。

+

Local-first · Single-user · MIT License

+