本地写作工作台

BookX Desktop 是本机托盘程序，通过系统浏览器打开工作台。文章、文档和配置仍是工作区中的普通文件；浏览器是编辑入口，不是内容数据库。

打开和切换工作区

bookx-desktop --workspace ./my-site

没有托盘环境时使用 bookx studio --workspace ./my-site，再打开终端提供的地址。

从侧栏底部或托盘菜单切换工作区，可以选择已有目录，也可初始化空目录。程序记录最近打开的 12 个目录。切换前会尝试保存内容和设置；保存失败时先处理错误再切换。

“移除”只清除最近打开记录，不删除目录。当前工作区不能移除，需要先切换到另一个工作区。每个已打开的工作区有自己的服务端口和会话，旧标签页仍属于原来的工作区。

写作与目录操作

博客和文档有独立的内容树。选择目录后新建，便于把内容直接放在正确位置。右键菜单提供编辑、重命名、删除、可见性及打开文件等操作；非空目录可以整体移入回收站，所有子目录、页面和附件一起保留。右键菜单会避开窗口边缘，窗口过小时可在菜单内滚动。

在工作台重命名或移动目录，会先保存已打开的文章和文档，再自动更新其他页面指向它的相对链接，以及移动后需要调整的内部链接。Markdown 图片、附件、引用式链接和相对路径封面一起处理，草稿、私有、仅本地内容及工作区根 README 也参与检查。成功后编辑器自动刷新；保存失败则取消，执行失败会尝试恢复原文件和目录。内容 ID 和显式 slug 保留，发布网址仍可能因文档层级变化而变化，需要重新构建并检查站外引用。在 Finder 或其他程序中直接改名不触发此更新。

排序支持标题、最新、最早和序号，并可切换升降序。通过拖动图标开始拖拽，完成后切换为持久化序号顺序；普通标题区域用于选中和展开。文档顺序只在同一级生效。升降序偏好在删除目录、切页和刷新后保留，保存失败会提示。

导航中的“回收站”可以搜索原路径、恢复或确认后彻底删除。恢复保留原内容 ID 和目录元数据；同名路径不会覆盖，父目录也被删除时请先恢复父目录。回收站保存在当前工作区，不参与构建和 Git 同步，也不会自动清空。普通页面删除只移动 Markdown 文件，公共图库资源继续保留。

删除和恢复后需重新构建对应预览：“构建站点”更新发布预览，“构建全部”更新本地预览。两种输出独立，构建失败时保留上一次成功结果；正式网站需重新发布。

编辑器提供结构化元信息、Markdown 工具栏、图片选择、预览与全屏入口。使用 Ctrl/⌘ + S 可以立即保存，离开页面前留意保存状态和错误提示。标签、关键词与旧链接别名分别填写，不要混成一个字段。

正式预览与全部内容预览

全部内容预览生成到 .bookx/preview/，使用独立本机端口，不覆盖正式 dist/，并关闭评论和统计。子目录的“显示目录首页”开关仍然生效；隐藏的首页不会因为全部构建而出现。

第一次使用“本地预览”前先点击“构建全部”。重复构建后刷新已经打开的页面。正式发布及发布检查会重新执行公开构建，不会把全部预览产物直接上传。

构建中两个构建入口会同时禁用重复提交。如果提示正在保存设置或其他操作占用，等待该操作完成再试；构建失败会保留上一次成功的产物。

图片库

上传的图片统一保存在 media/images/。内容图片按哈希引用，相同内容可跨页面复用。图库支持浏览、搜索、复制引用和删除未使用图片；编辑器的图片选择器可直接插入图片并设置宽度。

Logo、头像和浏览器图标可以在站点设置上传。工作台自己的 Logo 与配色不等于公开站点的 Logo 与主题。

设置什么时候生效

工作台配色、密度等偏好保存在本机；站点名称、主题、分页、SEO 等写入 bookx.yml。站点配置自动保存成功后，仍需重新构建才能更新正式页面。

站点主题外观面板默认折叠。展开后可以调整配色、文章列数、分区颜色、圆角等，并查看桌面／手机示意。示意图用于检查布局和颜色，最终内容以构建后的站点为准。

本机访问与源码同步

工作台只监听回环地址，启动时生成临时会话。请使用启动命令或托盘提供的地址，不要收藏带临时会话参数的链接作为永久入口。程序退出后，本机服务会关闭。

Git 同步和发布配置保存在 .bookx/local.yml。只有填写非空远程仓库地址才会启用启动自动更新；默认的 git、origin、main 文本不代表已经配置同步。同步步骤见同步与发布。