Issue 119 - ShaoClean/Alune GitHub Wiki

Issue #119：Markdown 文件支持 Preview 渲染预览

类型：功能
状态：已实现，本地验收通过，待审阅
Issue：https://github.com/ShaoClean/Alune/issues/119
PR：https://github.com/ShaoClean/Alune/pull/124
最近更新：2026-09-29
代码基线：development / 7f42589
实现提交：877538989f0b49b09aba57c0bf7e8982f795996f

背景与问题

文件视图原先将 README 等 Markdown 文档作为源码显示，阅读时无法直接看到标题、列表和表格的排版效果。本次为仓库文件增加只读 Preview，同时保留完整源码入口。

目标与范围

.md 扩展名大小写不敏感，默认使用 Preview，当前仓库会话内记住源码/Preview 选择。
支持标题、段落、强调、列表、引用、分隔线、链接、图片、行内代码及代码块，以及 GFM 表格、删除线和只读任务列表。
本地与 SSH 仓库都读取当前工作区文件；刷新同步更新文档和相同路径的图片。
沿用文件读取、空文件、权限错误和超限提示。切换模式只改变显示，不编辑文件或暂存区。
不包含编辑保存、渲染后的 Diff、MDX 执行、Mermaid 或数学公式。

方案与取舍

FilesView 继续通过现有目录/文件接口读取内容并取消过期请求。Markdown 文件在 CodeView 和新增 MarkdownPreview 之间切换，使用已安装的 react-markdown 与 remark-gfm，无需新增依赖或服务端接口。目录树、选中文件和会话状态沿用原有机制。

代码块按文本保留 Markdown 字符，不再次解析。标题生成包含中文的文档锚点，重复标题使用独立后缀。预览使用现有主题变量；长代码块和表格在各自区域横向滚动，图片保持比例并限制宽度。Markdown 超过 256 Ki 字符时暂停渲染并提示切换源码，服务端 1 MiB 文本/5 MiB 图片读取上限继续有效。

资源处理规则：

输入	行为
相对文件路径	以当前文档目录为基准；解码并规范化后通过仓库只读接口访问
以 `/` 开头的路径	以当前仓库根目录为基准，不访问系统绝对路径
仓库内文档链接	在文件视图打开，展开父目录并同步选中；可带标题锚点
`#标题锚点`	在当前文档内跳转；不存在时给出提示
路径查询参数	不参与仓库文件定位；文件名中的 `?`、`#` 可用 URL 编码
仓库图片	支持 PNG、JPEG、GIF、WebP；缺失、损坏、超限、符号链接或不支持的格式显示原因
HTTP(S) 链接	在外部浏览器或新标签页打开，带 `noopener noreferrer`
HTTP(S) 图片	默认显示说明，点击“加载外部图片”后请求，不发送 Referer
越界路径、`.git`、危险协议、原始 HTML	拒绝资源访问或忽略 HTML，不执行脚本；保留可理解的文本/图片回退

不改变现有仓库权限边界。Markdown 路径解析不使用应用地址作为基准；仓库图片请求沿用认证和 SSH 读取机制。外部图片加载按钮阻止冒泡，避免点击嵌套在链接中的图片占位符时意外打开链接。

验收标准

README 等 .md/.MD 文件能显示排版后的文档并切回完整源码。
反复切换模式保留选中文件，不写入文件；返回文件视图保留会话选择。
GFM 表格、只读任务列表、引用、代码块正确渲染；混合列表保留普通项目符号。
相对链接、中文锚点和图片有明确规则；无效图片不阻塞正文。
浅色、深色和窄窗口可读，长代码、表格及宽图片不撑破内容区域。
本地与真实 SSH 文件读取、刷新、相对资源和快速切换可用。
空白、空文件、渲染超限、读取超限、读取失败及非 Markdown 文件有对应展示。

验证记录

环境：macOS 15.5 / arm64，Node.js 25.5.0，ego-browser Chromium；日期：2026-09-29。

代码阶段 / 检查	命令或场景	结果
首次实现	`npm test -w web`	165 项通过；覆盖 Markdown 渲染、资源规则与现有文件视图
同步最新 `development` 后，`8775389`	`npm test -w web`	177 项通过，无跳过或失败
`8775389` 构建	`npm run build -w @alune/shared`、`npm run build -w @alune/ssh-client`、`npm run build -w server`、`npm run build -w web`	均通过；Vite 保留现有的大 chunk 提示
提交规范与差异	`npm run commitlint -- --last --verbose`、`git diff --check`	通过
首次实现浏览器验收	源码往返、只读任务列表、相对文件/中文锚点、图片缺失/损坏/符号链接/外部加载失败、危险输入、快速切换、空文件与超限、失败重试	通过；模式切换后临时仓库内容摘要和 Git 状态未变化
首次实现刷新验收	本地及真实 SSH 文档刷新、同路径图片内容/尺寸变化	通过；更新的文档和图片均显示最新内容
`8775389` 复验与截图	本地源码/Preview 切换、文件不变、真实 SSH 相对文档与图片、390px 窄窗口、深浅主题	通过；截图见下方
Windows/Linux 原生桌面及发行包	未手动运行	本次使用 macOS 浏览器和本机真实 SSH/SFTP fixture；不宣称已完成跨平台原生桌面验收

复验入口为代码仓库中的 apps/web/tests/markdown-preview-fixture.cjs。构建上述工作区后运行 node apps/web/tests/markdown-preview-fixture.cjs，会输出独立的本地/SSH 页面和测试控制地址。文件、Git 仓库及 SQLite 数据均位于临时目录，退出时清理。