把本地 Obsidian 知识库渲染成一座手绘涂鸦风的 2D 城邦——写笔记就是建设城市，笔记之间的链接就是城中的道路。一座"活的知识景观"。
Notopolis（note + polis）是一个纯本地运行的 Web 应用：它扫描你的 Obsidian vault，按确定性规则把笔记映射成建筑、目录映射成城区，实时渲染成一张可缩放、可漫游的城市地图。没有主动玩法——城市的样貌完全由你的知识库结构与新鲜度决定。
| 知识库 | 城邦 |
|---|---|
| 一篇笔记 | 一栋建筑（体量随字数） |
| 顶层目录 | 一个城区（不规则有机边界） |
| README | 区府 🏛 |
| 被引多的笔记 | 地标 ⭐ |
含 - [ ] 未完成任务 |
施工中的工地 🚧 |
| 久未修改的笔记 | 墨迹褪色的老建筑 |
| 笔记数量 | 营地 → 村镇 → 城市 → 都城 |
同一个 vault 永远渲染出同一座城市（种子化确定性布局）；不同 vault 按主题生成不同地貌（平原王城 / 海港商邦 / 雪原孤城 / 山地雄关），含河流、山脉、湖泊、铁路、机场、轮渡等元素。
- ⌘K 搜索定位：输入笔记名，镜头飞行到对应建筑并高亮。
- 工地清单：所有含未完成任务的笔记，按目录树组织，可展开/收起、一键定位或跳 Obsidian。
- 入城变化摘要：进城时播报「自上次到访：新建 3 栋 · 翻修 5 栋 · 完成 4 项任务…」。
- 知识透镜：一键切换图层——孤岛视图（高亮零链接笔记）、园丁视图（最久未打理的笔记）。
- 链接漫游：建筑卡片上列出入链/出链，点击即可沿链接在城中连续漫游。
- 笔记查看/编辑：卡片内「打开」弹窗，Markdown 渲染，支持就地编辑并保存回 vault。
- 随机漫步：随机重逢一篇冷门老笔记。
- 实时更新：文件监听（chokidar）+ WebSocket，改动即时反映到地图。
- 设置中心：右上角「⚙ 设置」弹窗，左菜单右内容——配置仓库（增删 Obsidian vault）、配置模型、向量库管理、主题切换，全部集中一处。
- 主题系统：6 套内置主题（荧光绿默认 / 抹茶 / 靛蓝 / 琥珀 / 黑白灰 / 暗夜），CSS 设计令牌驱动，一键整站换肤。
- 向量知识库（RAG，可选）：「设置 → 配置模型」接入千问嵌入/对话模型（本地 Ollama / 云端 DashScope，OpenAI 兼容协议）后，「常规」按钮的文书档案面板可按目录将文档切片向量化入库（已入库文档盖印章小标记，地图上对应建筑加书本屋饰）；⌘K 搜索多出「语义」「问答」模式——BM25+向量混合检索、RRF 融合重排，问答强制带引用、证据不足拒答，答案可 👍👎 反馈并沉淀为评估集（recall@k / MRR / 生成 / 引用四层指标）。「设置 → 向量库」提供统计 / 文档 / 切片三级管理页：重建、清空、按文档更新与移除、切片透视。未配置时一切行为与原版完全一致（松耦合）。
- 服务端：Node + Fastify + TypeScript（ESM），纯函数布局引擎，chokidar 文件监听，REST + WebSocket。
- 前端：Vite + TypeScript + 原生 Canvas 2D（地图手绘涂鸦风，doodle-slam 同源笔触；界面壳现代圆润风，CSS 设计令牌主题化），无 UI 框架。
- 向量库：自研文件型向量存储（
index.json+vectors.bin，归一化点积精确检索），零外部数据库依赖；VectorStore为接口，可替换后端。 - 测试：Vitest（402 用例）+ Playwright 冒烟。
npm install
npm run build # 构建前端到 web/dist
npm run dev # 启动服务，默认 http://localhost:4777首页即世界地图；首次打开会自动弹出「设置 → 配置仓库」，填入你的 Obsidian vault 绝对路径即可（之后可随时从右上角「⚙ 设置」打开；macOS 下若 vault 在受 TCC 保护的目录，需给终端授予「完全磁盘访问」）。
常用脚本：
npm test # 运行全部单测
npm run dev:web # 仅前端热更（Vite dev server, 5173）
NOTOPOLIS_PORT=4787 npm run dev # 指定端口运行数据全部落在 ~/.notopolis/（可用 NOTOPOLIS_CONFIG_DIR 覆盖）：config.json 为配置（apiKey 在接口层全程掩码往返），rag/<vaultId>/ 为向量库与反馈日志。
src/server/ # 服务端
layout/ # 纯函数布局引擎（城区/建筑/道路/铁路）
rag/ # 向量知识库（切片/嵌入/向量存储/混合检索/约束生成/评估/反馈）
scanner.ts # 扫描 vault → 笔记元数据
graph.ts # 链接图（入链/出链/孤儿）
diff.ts # 入城变化对比
web/src/
render2d/ # Canvas 2D 渲染（城市画师/动态层/相机/透镜/生物群系/向量印记）
ui/ # UI 组件（设置中心/向量库页/文书档案/主题/搜索/卡片/下拉/确认框/消息条）
views/ # 世界地图（手绘白板+动效小生物）/ 城市视图（桌面装裱图纸）
util/ # 搜索/目录树/Markdown 等纯函数
规则而非固定布局——所有地貌都由 vault 路径种子化生成，保证「同库同城、异库异貌」。只读优先——Notopolis 主要是知识库的观察窗，写作发生在 Obsidian；笔记编辑仅作为便捷补充（限 vault 内既有 .md，带路径穿越防护）。工具壳与画布分层——界面壳是现代圆润的工具风（胶囊按钮、大圆角、软投影、令牌化主题），地图画布保持手绘涂鸦的纸墨语言，城市图纸像作品一样「装裱」在桌面上，两层各说各的话又互不打扰。松耦合——RAG 等可选能力默认关闭，关闭时与原版行为逐像素一致。
MIT © Qiang Xue