# Atlas [![npm version](https://img.shields.io/npm/v/atlas-dashboard?color=5b9cff&label=npm&style=flat-square)](https://www.npmjs.com/package/atlas-dashboard) [![npm downloads](https://img.shields.io/npm/dm/atlas-dashboard?color=8b95a7&label=downloads&style=flat-square)](https://www.npmjs.com/package/atlas-dashboard) [![license](https://img.shields.io/npm/l/atlas-dashboard?color=8b95a7&style=flat-square)](./LICENSE) [![node](https://img.shields.io/node/v/atlas-dashboard?color=8b95a7&style=flat-square)](https://nodejs.org/) [![website](https://img.shields.io/badge/website-damonamber.github.io-5b9cff?style=flat-square)](https://damonamber.github.io/atlas-dashboard/) > 本地 HTML / Markdown 文档统一浏览/管理 dashboard。 > 扫描你指定的目录里的所有 `.html` 与 `.md` 文件（`.csv` / `.json` / `.txt` / `.svg` 可选开启），提供： > **首页未读概览** · **星图视图** · **时间河流** · **快速查看** · **专注阅读** · **多 Tab 浏览** · 目录树（嵌套分组、拖拽重排）· 备注名 · 未读标记 · **收藏夹** · **标签筛选** · **和上次已读版本对比** · ⌘K 快速打开 · 桌面通知 · 在访达打开 · ⌘B 收侧栏 · iframe 平滑预览 · Markdown 实时预览与编辑 · **Mermaid 图表与数学公式** · **HTML 沙箱预览** · **星图配色，深浅色主题可固定**。 适合的场景：你让 AI 在不同项目里到处生成 HTML 报告/原型/总结，浏览器 Tab 越积越多——Atlas 把它们汇聚在一处，AI 更新过的文档会亮起未读标记，看完即清。 🌐 介绍页：**https://damonamber.github.io/atlas-dashboard/** 📦 npm：**https://www.npmjs.com/package/atlas-dashboard** --- ## 安装与启动 零配置直接跑（不写到磁盘）： ```bash npx atlas-dashboard ``` 或全局安装： ```bash npm install -g atlas-dashboard atlas ``` 第一次启动会问你三个问题（全部都有合理默认值，回车跳过即可）： ``` 👋 欢迎使用 Atlas — 一次性配置后即可使用 ? 要扫描哪些目录的 HTML 文件？(多个用逗号分隔，支持 ~) 默认: ~/Documents › ? 监听端口？ 默认: 4321 › ? 要忽略的目录名？(逗号分隔) 默认: node_modules,.git,dist,build,... › ? 扫描最大深度？ 默认: 6 › ✓ 已写入 ~/.atlas/config.json → http://localhost:4321 ``` 之后再跑 `atlas` 直接启动，不再询问。 --- ## 命令 ``` atlas 前台启动（首次会引导配置；Ctrl+C 退出） atlas start 后台启动，立即返回，写 PID 与日志 atlas stop 停止后台服务 atlas restart 重启后台服务 atlas status 查看运行状态（pid / url / uptime） atlas log tail -f 日志（Ctrl+C 退出） atlas init 重新进入交互引导（仅配置，不启动） atlas --port 临时换端口（不写回配置） atlas --root 临时加扫描根（可重复，不写回配置） atlas --config 打印配置 / 日志 / PID 文件位置 atlas --version atlas --help ``` 最常用的两组： **临时跑一会儿（开发/调试）**： ```bash atlas # 前台启动，关终端就停 ``` **长期后台跑**： ```bash atlas start # 后台启动，关终端不影响 atlas status # 想用时看下还活着没 atlas stop # 不需要时停掉 ``` 例子： ```bash # 临时把桌面也扫上 atlas --root ~/Desktop # 临时换端口（4321 被别的服务占了） atlas --port 5000 # 重新配置 atlas init # 排查问题 atlas log # 实时跟随日志 ``` 被占用的端口会自动让位（4321 占用 → 试 4322 → ...），`atlas status` 会显示真实在跑的端口。 --- ## 配置文件位置 | 平台 | 路径 | |---|---| | macOS / Linux | `~/.atlas/` | | Windows | `%LOCALAPPDATA%\atlas\` | 里面是： - `config.json` — 扫描根目录、端口、忽略列表、扫描深度 - `store.json` — 你拖拽形成的虚拟分组、备注名、已读时间、收藏、标签、分享链接、已信任的 HTML、对比底本的索引 - `versions/` — 「和上次已读版本对比」用的底本快照（每个文件最近 5 份，都能在对比面板里选中查看或回退） - `backups/` — 编辑保存前的安全备份（每个文件最近 20 份） - `thumbnails/` — 首页封面用的真实缩略图缓存（PNG + `index.json`；删掉后会在需要时重新截图，`ATLAS_THUMBS=off` 启动时不生成） - `links/` — 星图连线用的引用关系缓存（`index.json`，按源文件记 mtime / 大小 / 指向的文档；删掉会在下次扫描后自动重建） - `activity/` — 时间河流用的活动日志（每天一个 `YYYY-MM-DD.jsonl`，一行记一次新增 / 修改 / Atlas 自己的保存；只保留最近 8 天，随时可以整个删掉，删了河流就按文件修改时间推断） 不用「编辑」功能的话，Atlas 不会动你扫描根下的任何文档——只读、只预览。 用了编辑 / 重命名功能才会写盘，而且写前一定先备份到 `backups/`。 可以用环境变量 `ATLAS_HOME` 把这些挪到别的地方（比如同步盘）： ```bash export ATLAS_HOME=~/Sync/atlas atlas ``` --- ## Dashboard 功能 - **首页概览**：没打开文档时，右侧是一屏「今天该看什么」。最上方是一条**按标签筛选**条（见下方「标签」）。**英雄区**眉标是「今日 · 周X」加当前时刻，一句大标题直接回答"今天 AI 改了几篇文档"（数字喷品牌渐变，是句子的一部分而不是一格格仪表盘），右侧一栏竖排读数「文档 / 项目 / 未读 / 近 7 天改动」（近 7 天改动与下方时间河流是同一个数；窗口窄时读数栏折到下方，再窄换成一行统计 chip）。英雄区下面是**时间河流**（见下）。再往下**待看队列铺成封面墙**——每篇一张封面卡（类型角标、新鲜的带未读标记），点一张直接进文档；本机装有 Chrome / Edge 等 Chromium 系浏览器时，封面是文档的**真实缩略图**（截的是页面首屏，放大到能看清标题，Markdown 封面不带目录栏、从标题和正文开头截起，类型角标在右下角；深色主题下白底的 HTML 页面会压暗，不刺眼）——Atlas 在后台按需截图（完全断网、只用 `file://` 打开源文件、碰不到 Atlas 自己的接口），缓存在 `~/.atlas/thumbnails/`，文档改了会自动重截；没找到浏览器、或页面依赖在线资源（CDN 脚本或样式）时，保留统一中性底色 + 类型字形的生成式封面（⚙ 设置 → 外观与通知 里写着当前用的是哪种）。不想让 Atlas 起浏览器截图，用 `ATLAS_THUMBS=off atlas` 启动即可彻底关掉；有标签 / 仅未读 / 搜索筛选时，待看只列命中的未读文档，计数后注明按什么筛的。**最近打开**与**收藏**收在最底部两条紧凑轨道里（最近打开的轨道头可一键清除）。整屏卡片错峰浮起入场，回首页走柔和的视图转场。 - **时间河流**：首页英雄区下方一张卡片，把**过去 7 天每小时的改动次数**画成 168 根柱（比例尺按大多数小时的改动量定：某一小时突然改了上百次也不会把别的柱压扁，这种尖峰画到顶并在柱顶标出真实次数；24 小时内的颜色更亮，右端一条「现在」刻线），卡片头写着「N 次改动 · 最忙 M/D HH:00（m 次）」，悬停一根柱看「几月几日几点 · 几次改动 · 几篇」。数据来自 Atlas 运行时记下的**活动日志**（`~/.atlas/activity/`，只记新增和修改，保留 8 天，可以随时删除）：同一篇 60 秒内连续写多次只算一次，你在 Atlas 里自己保存、回退不算 AI 的改动；Atlas 没运行的时段和日志建立之前，按每篇文档的最后修改时间补上（这部分铺一层淡斜纹底、标「仅修改时间」，因为每篇只知道最后一次改动；刚开始记录日志时，河流上方会写明「活动日志自 M/D HH:MM 起记录」，之前更早的改动补不回来）。在 Atlas 里**重命名**一篇文档时，它 7 天内的多次改动会折叠成修改时间处的一次。**刷选时间段**：在河流上拖动选出一段（吸附到整点）、拖两侧手柄调整、单击一根柱选中这一小时、双击清除；键盘上两个手柄 `←/→` 移一小时、`Shift+←/→` 移一天、`Home/End` 到两端；右上角预设「24 小时」「3 天」（都开放到现在，之后新改的文档会自动落进来）和「清除」。选了时间段后，目录树、首页、星图一起只看这段时间里改动过的文档：侧栏搜索框下方出现一枚「⏱ 10/3 14:00–10/4 09:00 ✕」（点它清除），树顶提示也会列出时间段；首页封面墙换成「10/3 14:00 – 10/4 09:00 改动了 23 篇」（按这段时间里最后一次改动倒序，旁边「在侧栏中列出全部」）。在首页或星图上按 `Esc` 也能清除时间筛选。时间筛选只在本次打开期间有效，重开 Atlas 总是从不筛选开始；选中的时段整个滑出 7 天范围时会自动清除并提示。 - **随时回到首页**：看完一篇想回到那屏概览，有三个入口——面包屑最左边的「⌂ 首页」、侧栏左上角的 Atlas logo、或者按 `Esc`。回首页不会关掉已打开的标签，随时点回去。 - **多 Tab 浏览**：像浏览器一样同时开多篇文档——每打开一篇就多一枚标签，点标签切换。**切换不重载**：每个标签有自己常驻的预览帧，来回切滚动位置、图表、展开状态都留着，不用等它重新渲染。已经开着的文件再点一次只是切回原标签，不会重复开。关标签点标签上的 ✕ 或中键点它，`⌘W` 关当前标签、`Ctrl`+`Tab` / `Ctrl`+`Shift`+`Tab` 前后切、`⌘1`–`9` 跳到第几个（`⌘9` = 最后一个）。**关掉 App 再打开，会恢复上次开着的那几篇标签和当前项**。 - **HTML + Markdown 双模**：在 ⚙ 设置里勾选要扫描的文档类型，HTML（`.html`/`.htm`）与 Markdown（`.md`/`.markdown`）**可同时启用共存**，默认就是这两种。目录树行尾用 `HTML` / `MD` 角标区分。 - **另外四种格式可选开启**：`.csv`/`.tsv`、`.json`、`.txt`/`.text`、`.svg`。**默认关闭**——AI 顺手导出的数据文件通常比正文多得多，全打开会把目录树冲淡，未读标记也跟着失真，而未读标记的价值全在于稀缺。需要时在 ⚙ 设置 → 扫描 里单独勾选： - **CSV / TSV** 渲染成可读表格，复用 Markdown 那套 data table 排版（表头对齐、斑马纹、行 hover、宽表横向滚动提示）。**数字列自动右对齐**，一列价格扫下来能比大小。解析按 RFC 4180 来：字段里的逗号、换行、`""` 转义都不会把行切错；分隔符自动嗅探（逗号 / 分号 / Tab / 竖线，欧洲区域导出的分号也认）。 - **JSON** 重新缩进并按 key / 字符串 / 数字 / 布尔 / null 上色。压缩成一行的文件也能看出结构。**不合法的 JSON 不白屏**：报出出错的行列位置，下面按原文显示，内容一个字不丢。 - **文本** 等宽排版、保留空白、长行软换行。 - **SVG** 以 `` 方式安全展示（浏览器不执行 `` 里的脚本），衬一层棋盘底纹，透明背景的图形也看得清边界。 - 这四种在 Atlas 里**只读**（没有编辑器，改数据文件该用对应的专业工具），但未读标记、版本对比、收藏、标签、⌘K、全文搜索、局域网分享、导出 PDF（SVG 除外）都照常可用。 - **Mermaid 图表与数学公式**：` ```mermaid ` 代码块渲染成图（流程图、时序图、状态图、类图、ER、甘特、饼图、思维导图……mermaid 支持的都行），`$…$` / `$$…$$` / `\(…\)` / `\[…\]` 里的公式由 KaTeX 渲染。AI 写的架构说明和指标定义大量用这两样，以前在 Atlas 里只是一段灰代码和一串美元符号。 - **渲染失败一定可读**：图表语法写错时显示 mermaid 的原始报错（好让你知道该让 AI 改哪一行），源码仍在原处；公式渲染不出来就显示 `$…$` 原文。不会出现空白框。 - 渲染好的图右上角有「源码」开关，随时切回去核对 AI 写的节点关系。 - **不会把价格当公式**：`单价 $5，折后 $4` 这类句子原样显示（边界规则照 Pandoc：开定界符后紧跟非空白、闭定界符前是非空白、闭定界符后不紧跟数字）。 - **按需加载**：没有图表 / 公式的文档一个字节都不下载（mermaid 有 3.5MB）。库都在本地，离线可用。 - 三条路径一致生效：只读预览、编辑器的实时预览、以及**导出的 PDF 与局域网分享页**。 - **Markdown 渲染**：本地相对路径的图片正常显示；YAML front matter 渲染成元信息块而不是乱码；代码块带语言标签与一键复制；`- [ ]` / `- [x]` 是真复选框；标题 hover 出锚点链接；**跟随系统深浅色**。含两个以上标题的长文档会自动出现**可折叠侧边目录**（按层级折叠展开、点击平滑跳转、滚动高亮当前章节，状态记忆）。目录栏**宽度可拖拽**（拖右缘那条线，双击复位，聚焦后方向键微调、按住 `Shift` 加速），宽度会被记住——标题长的文档不必再忍受截断。 - **阅读宽度三档**：预览页右上角有一组切换——**推荐宽度**（约每行 54 个汉字，长文阅读的舒适区间）/ **加宽** / **占满全屏**。点一下即换，也可以按 `[` / `]` 逐档调，选择记在本地并跨文档保持。十几列的数据表切到全屏一屏看全，读长文再切回推荐宽度。 - **专注阅读**：顶栏的专注按钮（四角框图标，「更多」菜单里也有）或按 `⌘.` 进入——侧栏、顶栏和标签栏一起收起，只留正文；Atlas 渲染的页面（Markdown / CSV 等）和已信任的 HTML 顶部会多一条细细的阅读进度条。退出：再按 `⌘.`、按 `Esc`，或点右上角的「退出专注 · Esc」胶囊（鼠标静止 2 秒后它会淡出，动一下鼠标或用 `Tab` 聚焦就回来）。**阅读宽度照常三档**：Markdown 的宽度切换在专注时移到左下角（带「宽度 [ ]」标签、实底高对比），与退出胶囊一起淡出 / 浮现，`[` / `]` 照常生效，和普通预览是同一份偏好——专注里切到加宽，退出后还是加宽。编辑中不能进入（先保存或取消）；回首页、关掉最后一个标签、正在看的文档被删除时自动退出；专注不会改动侧栏的展开 / 收起偏好，也不会被记住——刷新后一律是正常布局。Safari 里 `⌘.` 被浏览器占用（停止载入），请用顶栏按钮。沙箱里的 HTML 读不到滚动位置，不显示进度条；焦点在这类文档里时按 `Esc` 到不了 Atlas，点一下退出胶囊即可。桌面 App 里专注时窗口的红绿灯会一起隐藏，顶部 28px 仍可拖动窗口，菜单「显示 → 专注阅读」（`⌘.`）在任何焦点下都能进出。 - **表格**：按 data table 的规矩排版——表头与数据列严格对齐（`` 的浏览器默认值是居中而 `` 是左对齐，不显式声明的话每张表的表头都是歪的）、外框圈住边界、表头一层浅底、极淡斑马纹、行 hover、首列加重、数字按位对齐（价格和百分比一列扫下来能比大小）。Markdown 里写的 `|:--:|` `|---:|` 对齐照旧生效。**宽表横向滚动**，右缘给出「还有内容」的渐变提示（macOS 的滚动条平时是隐藏的，没有这个信号根本不知道右边还有五列）——不会再把中文压成一列一个字的竖排。 - **GFM 提示块**：`> [!NOTE]` / `> [!TIP]` / `> [!IMPORTANT]` / `> [!WARNING]` / `> [!CAUTION]` 渲染成带图标与配色的 callout（说明 / 提示 / 重要 / 注意 / 警告），而不是一段带 `[!NOTE]` 字面量的普通引用。在预览里改过它之后回写源码，类型标记仍然是 `[!NOTE]`。 - **Markdown 编辑器**：点「编辑」进入**源码 / 预览分栏编辑器**。分栏宽度可拖拽（双击复位）、两侧滚动百分比同步、可开侧边**大纲**。**光标或选区落在一边，另一边会同步标出对应的内容块**——光标所在块用细高亮，跨块选区把覆盖到的块全部标上，两个方向都生效。回车自动续列表（有序列表序号自增、任务项续出未勾选框）、`Tab` / `Shift+Tab` 多行缩进与反缩进、`⌘B` 加粗 / `⌘I` 斜体 / `⌘K` 插链接 / `⌘E` 行内代码 / `⌘S` 保存，另有一条格式工具栏。**预览区也支持直接所见即所得编辑**，并且只重写你真正改过的那几个块——表格对齐、段落软换行、front matter 都逐字节保留，不会给 git 留下满屏无意义 diff。编辑期间自动存本地草稿，浏览器意外关闭后可恢复。保存写回原文件，带内容哈希冲突检测与自动备份（存 `~/.atlas/backups/`）。 - **和上次已读版本对比**：未读标记告诉你"AI 动过这个文件"，顶栏的**对比**按钮告诉你"动了什么"。它会拿磁盘上的当前内容和**你上次看到的那一版**逐行 diff（绿色新增 / 红色删除 / 未改动的大段自动折叠，上下文行数可调）。看完点「标记为已看过」即把当前内容设为新底本。 - **保留最近 5 版，可挑任意一版对比**：面板顶部的下拉列出留存的历史版本（带时间，与当前内容相同的那一版会标出来）。默认对比的是"最近一个内容不同的版本"——打开文档这个动作本身会记一份底本，如果直接拿它当基准，看到的永远是空 diff。 - **可回退**：选中某一版后点「回退到这一版」，把磁盘上的文件内容改回去。写入前自动备份到 `~/.atlas/backups/`，回退本身不可撤销，所以会先让你确认。 - **不会误报**：顶栏那个"有改动"的高亮以**内容**为准，不只看修改时间。AI 用相同内容重新生成一遍文档（或 `touch`、网盘同步）会让 mtime 前进但内容没变，这种情况不再亮起提示——以前会亮，点开却说"完全一致"。 - 底本存在 `~/.atlas/versions/`。你自己在 Atlas 里编辑保存、或执行回退之后，底本会同步更新——对比要回答的是"别人动了什么"，不该把你自己刚写的内容列成变更。 - **目录树（分组 / 目录两种视图）**：搜索框下方的树头左侧是**分组 / 目录 / 星图**切换（星图见下），右侧依次是**排序按钮**、全部折叠 / 展开和计数。层级一眼可辨：文件夹行（中性色文件夹图标，展开时换成打开的形状）比文件行大一号、加粗；每层缩进 19px 并画一条引导线，当前文档所在的那条支线引导线会带上品牌色；同一层的文件名与文件夹名起点对齐，类型只看行尾的 `HTML` / `MD` 角标。 - **排序与仅未读**：点树头的排序按钮弹出菜单——排序方式（名称 / 时间 / 自定义，拖动文件即切到自定义）、「仅未读」勾选项、以及一段「按标签筛选」。按钮上的小字显示当前排序（开了仅未读会显示「时间 · 未读」），悬停看完整的排序与筛选状态；`Esc` 或点菜单外关闭。 - **分组**（默认）：按你扫描根下的一级目录自动归类，可拖拽重排、新建嵌套分组、双击重命名分组、归档。深层嵌套的文件会在行上补一个中间目录提示，让同一分组里多个同名文件（README、index……）也分得清各自在哪个子目录；空间不够时优先保证文件名，目录提示先缩短（省略号在开头，末级目录始终看得到），侧栏拖得较窄时整段隐藏——完整路径在悬停预览和提示文字里。每一行高度固定，悬停时操作按钮浮在行尾，不会挤动别的行。 - **目录**：完全按磁盘上的真实多级目录结构展示——二级、三级子目录都逐层展开，和在访达里看到的一样。它是磁盘的只读镜像，不参与拖拽 / 归档，专治"深层目录被压平成一级、几个 README 挤在一起看不出区别"。 - 两个视图都支持**全部折叠 / 全部展开**（一个按钮两个状态），选择记在本地、刷新后保持。hover 自动归类的分组 / 目录节点会出现**在访达中显示**按钮，直接跳到它对应的磁盘目录（手工建的虚拟分组没有对应目录，不显示这个按钮）。 **重命名是稳的**：自动归类的分组内部带一个与项目目录绑定的身份标记，改过名之后即使分组临时变空（AI 覆盖写文件时会先删再建）、被归档再恢复，名字都不会被自动名顶替。 - **星图**：树头分段控件的第三项「星图」（或点首页英雄区里的迷你星图）把主区换成一张星图——每个项目是一个**星团**，每篇文档是一颗**星**（篇数很多的项目星团按对数放大，不会把只有几篇的小项目挤成一个点；星团之间始终留出空隙，项目名会避开别的星团的星点），**亮度 = 新鲜度**（1 小时内 / 24 小时内 / 7 天内 / 更早四档），未读的星是一颗实心亮点，本次打开 Atlas 后 AI 刚改过的会轻闪 3 次。**连线 = 引用关系**：A 文档里有指向 B 的相对链接（Markdown 的 `[..](..)` / 引用式定义、HTML 的 ``）时才画线，没有引用就不画。缩放分三档：**远景**只看星团分布和星团之间的聚合弧线（越粗引用越多），**中景**显示星点和最新文档的名字（悬停一颗星或一个星团时才画星团内部的引用线），**近景**显示文档名并淡淡画出星团内的全部引用；悬停或选中一颗星时，完整高亮它的入链和出链。拖动平移、滚轮或触控板捏合以光标为中心缩放、双击放大、右下角三个按钮放大 / 缩小 / 显示全部；悬停一颗星显示名字、项目、多久前更新和「引用 n · 被引用 m」，停留片刻弹出快速查看，点一下打开。侧栏的搜索 / 仅未读 / 标签筛选同样作用于星图：不命中的星淡成灰点、点不到，左上角写明「命中 n / 总数」。右侧**星表**是等价的键盘界面：列出全部星团（按最近改动排序），`↑↓` 移动、`Enter` 展开星团再打开文档、`Space` 快速查看，聚焦一颗星时画布会移过去并画出焦点环；窄窗口下星表默认收起。进入星图时**侧栏自动收起**、离开（选回分组 / 目录、打开文档）后自动恢复，这不会改动你的侧栏偏好；在星图里按 `⌘B` 就按你的选择来。引用关系由 Atlas 在后台解析（每篇只读前 512KB；启动后的头几秒先让出给界面，再开始解析），缓存在 `~/.atlas/links/`，文档改了只重解析那一篇。首页的迷你星图横向铺满整张卡片。 - **预览区轻量编辑**：点工具栏「编辑」可在预览里直接改文案、拖动 `ul/ol` 列表项、表格行、以及同类卡片组（同标签+同 class、≥3 个、连续）排序，所见即所得。点入链接文字还会浮出小编辑条，可顺便改超链接地址。hover 高亮提示可编辑处；脚本/图表/代码块等风险内容自动不可编辑。保存只改你碰过的源码、其余字节不动（不会破坏图表与格式），写前自动备份（存 `~/.atlas/backups/`），取消即还原。 - **拖拽**：文件拖到任意分组（含根级别），分组拖到分组内（嵌套）。folder 不会被拖进自己内部（系统会拦截）。**拖文件悬停在折叠 folder 头上 600ms 自动展开**——直接拖进去。 - **最近打开**：首页底部的「最近打开」轨道，以及 `⌘K` 还没输入时的「最近打开」段（最多 8 条），跨项目秒回——阅读文档时首页不可见，按 `⌘K` 就能一步回到刚看过的。段头 / 轨道头右侧的**清除**一键清空这份浏览记录（确认后生效，只清列表本身——未读标记、收藏和标签都不动）。 - **⌘K 快速打开**：模糊匹配文件名 / 备注 / 项目名（`aprt` 能命中 `api-report`），`↑↓` 选、`Enter` 打开。**也搜正文**——文件名匹配排在前面，文件名没命中但正文里有的另成一组「正文命中」，每条带**上下文摘要**（关键词已标出）和**这篇里出现了几处**。选正文命中项回车，预览会直接**滚到第一处并高亮**，顶栏出现 `n / m`，用 ▲▼ 继续在命中处之间跳。这一路不写侧栏搜索框，所以目录树不会被顺带过滤。**在预览的文档正文里按也照样生效**——不用先点侧栏把焦点拿回来（`⌘B` 同理）。 - **⌘F 文档内查找**：在当前打开的文档正文里逐词查找并高亮，右上角浮出查找栏显示 `n/m`，`Enter` / `Shift+Enter`（或 `↑↓`）在命中处之间跳。这和 `⌘K`（跨文档快速打开 / 全文搜索）是两件事——`⌘F` 只在**这一篇**里找。搜完 `Esc` 关闭查找栏并清掉高亮。桌面 App 里 `⌘F` 由应用菜单接管；浏览器里若被系统查找拦截，可用查找栏或 `⌘K`。（沙箱预览的 HTML 需先点盾牌信任才能在文档内查找。） - **退出文档内搜索**：`⌘K` 从「正文命中」进入某篇后会高亮命中并在顶栏显示 `n/m` 命中条。想清掉高亮但**不离开文档**，点命中条右侧的 ✕，或按一次 `Esc`（再按一次 `Esc` 才回首页）。 - **快捷键清单**：按 `?` 唤出速查表（侧栏底部和首页也各有一个入口）。打开文档后照样能查，焦点落在预览正文里也能按。完整清单见下方「[快捷键](#快捷键)」。 - **键盘导航**：搜索框按 `↓` 进入文件列表，`↑↓` 切换，`Enter` 打开，`Esc` 回搜索框。所有弹窗支持 `Esc` 关闭，`Tab` 焦点锁在面板内。 - **快速查看**：鼠标在目录树文件行、非当前的标签、首页封面或轨道行上停留片刻，旁边弹出一个小预览（标题、类型 · 项目 · 多久前更新、页面缩略图）；在多行之间移动时内容立即跟着换，移开、点击、滚轮或 `Esc` 就收起。键盘上，目录树焦点行按 `Space` 打开 / 关闭，开着时 `↑↓` 换内容、`Enter` 直接打开、`Esc` 只关预览（焦点留在原行）；`⌘K` 还没输入时按 `Space` 也能看选中的那篇。已有缩略图时直接显示截图；还没有时用一个只允许脚本、拿不到 Atlas 任何权限的沙箱页面实时加载（即使文档已被信任也一样）。快速查看不会把文档标成已读。**注意：悬停预览会像打开文档一样加载页面，包括它引用的在线资源**（CDN 脚本、图片等）；不想这样可以在 ⚙ 设置 → 外观与通知 → 悬停预览 里关掉，`Space` 仍然可用。 - **未读标记**：基于文件 `mtime` 检测。点开预览即清除；右上角有"标为未读"和"全部已读"。已归档的分组不参与未读统计——树里看不见的文档不会再挂在底栏那行数字上。未读标记用品牌强调色（蓝紫色实心小圆点），**按新鲜度分两档**：24 小时内改动过的是满亮度圆点 + 加粗，更早的降级成浅一档的圆点 + 常规字重（文件行、分组、首页待看队列、⌘K 结果都一致）。文档攒到几百篇时整列全亮等于没有信号，这样"AI 刚动过哪几个"才扫得出来——两档都算未读，筛选和计数不受影响。本次打开 Atlas 之后才被改动的文档（AI 改的，不含你在 Atlas 里自己的保存、回退和重命名），未读标记会轻闪 3 次再静止。红色只用来表示错误和危险操作（删除确认、导出失败、回退等）。 - **收藏夹**：hover 文件行，行尾操作组里的第一个就是星标（或预览时用右上角的星标按钮），点一下收藏、再点取消；已收藏的文件在名字后有一颗小实心星。首页「收藏」轨道和 `⌘K` 还没输入时的「收藏」段把散落在各个分组里的常看文档聚到一处，按最近收藏排序，跨文件夹一眼可达（`⌘K` 里每篇只出现一次：已在「最近打开」里的不重复列）。 - **标签 + 按标签筛选**：hover 文件 → 标签按钮 → 逗号分隔输入（`周报, 待评审, AI`），最多 12 个。首页最上方出现一条**按标签筛选**条（chip 按用量排序、带计数，多了可以横向滚动），点一下只看该标签的文档，**选多个标签是"同时具备"**，且与搜索、"仅未读"叠加生效。目录树和首页待看同时按它筛选，筛选条右侧写着「命中 n 篇」，和目录树计数「命中 / 总数」是同一个数。阅读文档时也能改：树头排序菜单里有同一份「按标签筛选」。筛选生效时目录树顶部会出现一行提示（如「已按标签筛选：周报 · 仅看未读」，有时间河流的时间段时也列在这里），点它右侧的**清除**一次撤掉提示里列出的标签、仅未读与时间段。清空输入并确定即删除全部标签。 - **备注名**：hover 文件 → 铅笔按钮 → 起一个你能记住的名字。原文件名不变。 - **重命名文件**：hover 文件 → 文件+笔按钮 → 直接改磁盘上的真实文件名（备注、已读状态、收藏、标签、分组位置都会跟着迁移）。 - **搜索**：搜索框（按 `/` 聚焦）匹配文件名 / 备注 / 路径 / 项目名，**也搜文档内容**（仅内容命中的文件会标 🔍）。空格分隔的多个关键词按"都要出现"过滤（`配网 转化率`），需要整段短语用引号（`"error rate"`）。 - **桌面通知**：⚙ 设置里勾选"桌面通知"，AI 更新 HTML 时弹系统通知。需要浏览器允许通知权限。 - **在访达 / 资源管理器中显示**：每个文件的文件夹按钮，跨平台（macOS `open -R` / Windows `explorer /select` / Linux `xdg-open`）。 - **用 Atlas 打开文件（桌面 App）**：Atlas 桌面版会注册为 `.md` / `.markdown` / `.html` / `.txt` / `.csv` / `.json` / `.svg` 的可选打开方式。在访达里双击这类文件、或右键「打开方式 → Atlas」，就直接在 Atlas 里打开这一篇（命令行 `open -a Atlas xxx.md` 同理）。如果这个文件还不在任何扫描根内，Atlas 会先问你要不要把它所在的目录加进来，确认后再打开——不会静默改动你的扫描配置。（这是"可选"打开方式：不会抢走 `.md` 的默认应用。） - **HTML 沙箱预览与信任分级**：预览用的是 Atlas 自己的源（`localhost:4321`）上的 iframe，而里面那份 HTML 是 AI 写的。同源意味着它的脚本能调 Atlas 的接口——改写磁盘上别的文档、开局域网分享链接、读扫描根配置。所以现在 **HTML 默认在沙箱里预览**： - 保留 `allow-scripts`，文档自己的脚本照常运行，**图表、交互、动画都不受影响**；但不给 `allow-same-origin`，它的源变成 opaque，碰不到 Atlas 的任何接口和数据。 - 代价是那几项需要注入的能力用不了：**预览内编辑、⌘K 正文命中高亮、⌘K/⌘B 快捷键转发、滚动位置恢复**。需要时点顶栏的**盾牌**按钮信任这一篇，立刻切回同源、能力全部恢复（点编辑按钮时也会直接问你要不要信任）。信任是按文件记的，存在 `~/.atlas/store.json`。 - Markdown / CSV / JSON / 文本 / SVG 的预览页是 Atlas 自己渲染的，内容全部转义过，**不走沙箱**——那样只会白白砍掉滚动恢复和正文高亮。 - ⚙ 设置 → 安全 里有全局开关「信任所有本地 HTML」（回到 0.17 及更早的行为）和「清空单篇信任记录」。 - 服务端还有第二道锁：**写类接口校验 Origin**，沙箱文档发出的请求（`Origin: null`）、别的站点、本机其它端口的页面都会被 403 挡掉。命令行工具不带 Origin，照常可用。 - **设置弹窗**：左侧分区（扫描 / 外观与通知 / 安全 / 分享 / 归档），右侧每一节是一张卡片；弹窗高度固定，切换分区时不会上下跳，内容多时在弹窗内滚动。 - **深浅色主题**：默认跟随系统。⚙ 设置 → 外观与通知 里可固定成**浅色**或**深色**，选择会被记住，**Markdown 预览页跟着一起固定**，不会出现"外壳浅色、正文深色"的割裂。 - **界面色调（冷 / 暖中性）**：⚙ 设置 → 外观与通知 里另可选中性灰的冷暖——**冷灰**是默认（偏工具感），**暖灰**更柔和、有纸感。它只调 Atlas 外壳与首页的中性色，主色、封面色与文档内容都不动，和浅色 / 深色两两正交（四种组合都自洽）。选择记在本地。同一页还有**界面动效：跟随系统 / 减少**——默认跟随系统的「减少动态效果」；选「减少」后转场、错峰入场、未读标记的轻闪都停下，信息照常显示（它只能让界面更安静，系统要求减少时不会强行打开动效）。桌面 App 里把主题固定成浅色或深色时，窗口材质会跟着切换，**文档里按系统深浅自适应配色的页面也会跟着 Atlas 的主题走**（浏览器版里这类页面始终跟随系统外观；选「跟随系统」时两边完全一致）。 - **侧边栏**：可拖拽调宽（中间 5px 拖拽条），可收起（⌘B / 顶栏左上图标）。侧栏只留搜索、树头和目录树；底部常显「N 篇文档 · M 未读」，树头计数在有筛选时显示「命中 / 总数」。 - **统一的图标与配色（星图配色）**：界面全部使用同一套线性图标（不再混用 emoji，跨平台字形一致）。配色走一层设计令牌、深浅色为同一份来源：深色是深空蓝黑底，浅色是星图纸底（首页英雄区背后衬一层很淡的星点 / 点阵）；只用一个品牌强调色（蓝紫）加中性色，新鲜度用同一色相的明暗表达，未读用强调色，红色只留给错误和危险操作。小字与语义色均满足 WCAG AA 对比度。 - **macOS 原生外观（桌面 App）**：窗口去掉了标题栏，红绿灯嵌进顶栏、与顶栏中线对齐，Atlas 图标和收起按钮与红绿灯之间留出间距；侧栏透出桌面壁纸的毛玻璃材质（浅色、深色都看得出来）。想要实底：系统设置 → 辅助功能 → 显示 → 打开「降低透明度」，侧栏立即改为实底（⚙ 设置 → 外观与通知 →「侧栏透明度」写着当前状态）。顶栏空白处（包括面包屑的文字）可拖动窗口，双击按系统设置缩放 / 还原；全屏时撤掉为红绿灯留的内边距。切换主题或冷 / 暖色调时整页柔和淡入，减少动态效果时直接切换。专注阅读时红绿灯一起隐藏（见「专注阅读」）。 - **局域网分享**：hover 文件 → 🔗 → 生成不可猜的 token URL + 二维码，同 Wi-Fi 的同事扫码即看（Markdown 会展示渲染后的页面）。**默认只放行这份文档真正引用到的资源**，同目录其它文件访问不到；页面在 JS 里动态拼路径导致缺图时可切成「同目录全部资源」。**链接默认 2 小时后失效**（可选 30 分钟 / 24 小时 / 不过期），也能一键停止全部。 - **导出 PDF**：HTML 与 Markdown 都支持，调本机 Chrome / Edge / Brave headless 渲染，保存到 `~/Downloads/`。Markdown 走打印版排版：不带目录侧栏、配色钉回浅色、标题不吊在页尾，**塞不进纸宽的宽表会自动逐档收紧字号**而不是被纸边裁掉右边几列。没装 chromium 系浏览器会降级到浏览器打印对话框。 - **多扫描根**：在 ⚙ 设置面板增删，立即生效。 - **iCloud 云盘**：macOS 上可以在 ⚙ 设置 → 扫描里一键「添加 iCloud 云盘」。只在云端、没下载到本机的文件照常列出，但显示为灰色并带「在 iCloud 中」标识；扫描、搜索、预览都不会读取它们，所以不会触发下载。需要时点「下载到本机」（文件行悬停时的下载按钮，或打开后占位面板里的按钮），下载完成后自动恢复正常，不会因为下载而亮起未读或弹通知（能否由 Atlas 发起下载取决于系统能力；不支持时可以在访达中右键文件选「立即下载」）。引用了未下载资源（图片、样式等）的文档不生成真实缩略图，保留生成式封面；导出 PDF 时会提示先下载这些资源。某些网络盘 / FUSE 文件系统或透明压缩的本地文件可能被误判为「在 iCloud 中」（灰显、不能预览），这时用 `ATLAS_CLOUD_DETECT=off atlas` 启动即可关掉这项判定。 --- ## 快捷键 应用内按 `?` 就能看到这份清单（侧栏底部的键盘图标、首页的「全部快捷键」按钮同效）。 macOS 用 `⌘`，Windows / Linux 用 `Ctrl`。 | 场景 | 按键 | 作用 | |---|---|---| | 全局 | `⌘K` | 快速打开：模糊匹配文件名，同时搜正文；再按一次收起 | | | `⌘F` | 在当前文档内查找（`Enter` / `↑↓` 在命中处间跳，`Esc` 关闭） | | | `/` | 聚焦搜索框 | | | `⌘B` | 收起 / 展开侧边栏 | | | `⌘S` | 保存改动到文件（编辑态） | | | `⌘.` | 进入 / 退出专注阅读（Safari 里请用顶栏按钮） | | | `?` | 打开快捷键清单 | | | `Esc` | 由近及远地退出：关快速查看 → 退出专注阅读 → 收起排序菜单 → 关查找 → 清空搜索 → 清除文档内高亮 → 收起对比 → 回到首页 → （首页 / 星图上）清除时间河流的时间段筛选 | | 多标签 | `⌘W` | 关闭当前标签（无标签时关窗） | | | `Ctrl`+`Tab` / `Ctrl`+`Shift`+`Tab` | 切到后 / 前一个标签 | | | `⌘`+`⌥`+`←`/`→` | 切到前 / 后一个标签 | | | `⌘1`–`9` | 跳到第 1–9 个标签（`⌘9` = 最后一个） | | 快速打开面板 | `↑` `↓` | 上下选择 | | | `Home` / `End` | 跳到第一条 / 最后一条 | | | `Enter` | 打开选中的文档（正文命中项会直接跳到命中位置） | | | `Space` | 还没输入时：快速查看选中的文档 | | 侧栏与目录树 | `↓` | 在搜索框里按 `↓` 进入文件列表 | | | `↑` `↓` | 在列表里移动（第一条再按 `↑` 回搜索框） | | | `Enter` / `Esc` | 打开当前文件 / 退出列表回搜索框 | | | `Space` | 快速查看焦点行（再按关闭；开着时 `↑↓` 换内容，`Esc` 只关预览） | | | 双击 | 双击分组名或文件名即可重命名 | | 星图 | `←` `→` | 视图分段控件上：在分组 / 目录 / 星图间切换 | | | `↑` `↓` `←` `→` | 画布获得焦点时平移 | | | `+` / `-` | 画布获得焦点时：放大 / 缩小（滚轮与触控板捏合同效） | | | `0` | 画布获得焦点时：显示全部 | | | `Enter` | 画布上：焦点移到星表；星表里：打开星团 / 文档 | | | `Space` | 星表里：快速查看选中的星（开着时 `↑↓` 换内容，`Esc` 只关预览） | | 时间河流 | `←` `→` | 手柄上：移动一小时 | | | `Shift+←` `Shift+→` | 手柄上：移动一天 | | | `Home` / `End` | 手柄移到最左 / 最右（两手柄在两端 = 不筛选） | | 正文命中导航 | `Enter` | 焦点在搜索框时跳到下一处命中 | | | `Shift+Enter` | 跳到上一处命中 | | Markdown 预览 | `[` / `]` | 阅读宽度收窄 / 放宽一档（推荐 → 加宽 → 占满全屏） | | Markdown 编辑器 | `⌘B` `⌘I` `⌘E` | 加粗 / 斜体 / 行内代码 | | | `⌘K` | 插入链接 | | | `Tab` / `Shift+Tab` | 多行缩进 / 反缩进 | | | `Enter` | 自动续列表（有序序号自增、任务项续出未勾选框） | | 编辑器分栏条 | `←` `→` | 聚焦分栏条后微调宽度（按住 `Shift` 加速） | | | `Home` | 宽度复位（双击分栏条同效） | | 重命名 / 备注 | `Enter` / `Esc` | 提交 / 取消 | **焦点落在预览的文档正文里时，`⌘K` / `⌘B` / `⌘.` / `?`（以及编辑态的 `⌘S`）同样有效**—— 预览是独立文档，键盘事件本来传不到外壳，Atlas 会把这几个和弦转发过来。 单键 `/` 和 `Esc` 刻意不转发：不少 HTML 报告自己用 `/` 做站内搜索、用 `Esc` 关自己的浮层， 抢过来会把文档本身的交互弄坏。读文档时想回首页，点面包屑的「⌂ 首页」或侧栏 logo。 唯一的例外是专注阅读：专注时文档自己没处理的 `Esc`（没有 `preventDefault`）会转发过来，用来退出专注。 --- ## 让 AI 不要再每次打开 HTML Atlas 解决了"散乱 + 浏览器 Tab 爆炸"，但**自动 `open xxx.html`** 是 AI 端的行为，需要你告诉它别这么做。把这条加到 `~/.claude/CLAUDE.md`（或对应 AI 工具的全局规则）： ``` 生成或更新 HTML 文档后，不要执行 open / xdg-open 打开浏览器。 本机运行着 Atlas dashboard（http://localhost:4321），它会自动通过 mtime 显示未读标记。 ``` --- ## 跑在后台 直接 `atlas start` 即可——内置的守护进程管理已经处理好 PID、日志、健康检查、端口冲突自动切换。**不需要写 nohup/alias 这些手工脚本**。 如果想开机自启（macOS launchd 示例）： ```bash cat > ~/Library/LaunchAgents/com.atlas.dashboard.plist <<'EOF' Label com.atlas.dashboard ProgramArguments /usr/local/bin/atlas RunAtLoad KeepAlive StandardOutPath /tmp/atlas.log StandardErrorPath/tmp/atlas.err.log EOF launchctl load ~/Library/LaunchAgents/com.atlas.dashboard.plist ``` 如果 `which atlas` 输出的不是 `/usr/local/bin/atlas`，把 plist 里的路径替换成你实际的（一般是 `/Users//.npm-global/bin/atlas`）。 --- ## 故障排查 ```bash atlas --config # 打印配置文件路径 cat ~/.atlas/config.json # 看当前配置 atlas init # 删配置重新来一遍 rm ~/.atlas/store.json # 重置目录树/已读状态（不影响磁盘 HTML） ATLAS_HOME=/tmp/atlas-debug atlas init # 用临时配置不污染主配置 ``` 如果 `atlas` 启动后扫不到文件，检查： 1. `~/.atlas/config.json` 里 `scanRoots` 是不是绝对路径 2. `maxDepth` 够不够（默认 6 层） 3. 文件是否在 `ignore` 名单的目录里（`node_modules` `.git` 等） 4. 文件类型是否已启用（`docTypes` 默认只有 `["html","md"]`，csv / json / txt / svg 要在 ⚙ 设置里勾） 其它常见疑问： - **导出 PDF / 在访达中显示 / 自动升级报错或没反应**（macOS、0.19.0 之前）：扫描根很大时，旧版的文件监听会为每个目录占一个文件描述符（macOS 的 kqueue 就是这么工作的），进程 fd 数一旦越过 10240，**Atlas 就再也起不了任何子进程**——导出 PDF 稳定失败，另外两个时好时坏。0.19.0 换成系统级的递归监听后，fd 从上万降到几十。Linux 不受影响（inotify 不按目录占 fd）。如果你还在旧版上，临时绕法是把扫描根收窄到更具体的子目录。 - **添加扫描根时提示"这个目录很大" / 底栏出现「⚠ 已达上限」**：Atlas 会在添加扫描根前估算目录里的文档数，很大（约 5000 篇以上）就先让你确认——扫描和监听超大目录更慢也更占内存。为守住内存，索引还有一个总数硬上限（默认 5 万篇），撞到后会停止收录多出来的文档，底栏用「⚠ 已达上限」明示。建议把扫描根收窄到更具体的子目录，或在 ⚙ 设置里补充"忽略的目录名"。确实需要更高上限的，可用环境变量 `ATLAS_MAX_INDEX_FILES` 覆盖（自行承担内存代价）。 - **预览里的编辑按钮点不动 / ⌘K 跳不到正文命中处**：这篇 HTML 还在沙箱里。点顶栏的盾牌信任它，或在 ⚙ 设置 → 安全 里打开全局开关。 - **Mermaid 图表显示成代码块**：先确认代码块的语言标记就是 `mermaid`；如果显示的是一段红色报错，那是 mermaid 的语法诊断，把它贴给 AI 让它改。 --- ## 维护者文档 - **[PUBLISHING.md](./PUBLISHING.md)** — 发版的标准流程（npm publish + GitHub Release + CI 验证）。**任何改动了发版方式的 PR 必须同步更新此文件**。 - **[.github/workflows/](./.github/workflows/)** — CI / Release 自动化配置。 ## License MIT