SkyJourney
58087d0c7e
新增共享 Preview Engine，统一 Web 连续预览、快速分页、Playwright PDF 与 Electron PDF；实现稳定前缀复用和修改位置后的增量分页，保留媒体块按文档顺序串行回填与单次重排。 完善跨端链接与桌面文档工作流：Web 受控处理锚点和 HTTP/HTTPS 外链；Desktop 支持本地路径、file URI、系统协议、多窗口、同文件单例、Markdown 当前或新窗口打开，以及聚焦时外部文件变化提示。 统一四套内置主题名称并默认使用 Typora Github；修复连续预览双滚动条、ECharts 尺寸、PDF 本地链接、围栏代码块 Typora DOM 与重复行内样式；桌面发行链强制完整重建内嵌 Web，避免安装包携带陈旧资源。 发布 Web/Compose 与 Windows NSIS/ZIP：镜像 yixiong/md-to-pdf:v0.5.0 已健康部署；NSIS SHA-256 为 60992D1FDCA513F46346C78478537EB4159D8C0E76B41ECF3CDC25BE77707D92，ZIP SHA-256 为 D74F82293FB67126E583546CBA894569EFC9A0B1B6343FAC648CCC95F1D188D8，本机安装版已升级至 v0.5.0。 验证：全项目 238 项测试通过，类型检查、生产构建和 git diff --check 通过；Web 快速/连续/精确预览、Compose、Desktop 多窗口、窗口状态、文件关联、链接与代码块均完成真实环境验收。
206 lines
8.1 KiB
Markdown
206 lines
8.1 KiB
Markdown
# AGENTS.md
|
||
|
||
本文件适用于仓库根目录及其所有子目录。进入本项目的新会话必须先完整阅读本文件与 `docs/PROGRESS.md`。
|
||
|
||
## 1. 语言与沟通
|
||
|
||
- 所有解释、询问、进度汇报、提交说明和项目文档必须使用简体中文，代码及必要的技术标识除外。
|
||
- 涉及架构调整、新功能模块或明显改变现有实现方向时，先用文字或 Mermaid 对齐设计，等待用户确认后再编码。
|
||
- 开始实质性任务前列出任务清单，等待用户明确确认。
|
||
- 修改、新建或删除文件前，简要说明具体变更范围，等待用户确认。
|
||
- 代码量较大或逻辑复杂时分步执行；每完成一个阶段，汇报结果并等待用户确认是否继续。
|
||
- Mermaid 中的中文标题和节点文字必须使用英文双引号包裹。
|
||
|
||
## 2. 会话启动检查
|
||
|
||
新会话、上下文压缩后或对当前目录不确定时，在执行其他 Shell 命令前先运行：
|
||
|
||
```powershell
|
||
Get-Location
|
||
```
|
||
|
||
确认目录为：
|
||
|
||
```text
|
||
C:\Projects\md-to-pdf
|
||
```
|
||
|
||
随后依次执行只读检查：
|
||
|
||
```powershell
|
||
git status --short
|
||
git log --oneline -5
|
||
Get-Content -LiteralPath 'docs\PROGRESS.md' -Encoding UTF8
|
||
```
|
||
|
||
当前工作区可能包含用户或上一个会话留下的未提交修改。禁止使用 `git reset --hard`、`git checkout --`、`git clean` 等方式丢弃修改，除非用户明确要求。
|
||
|
||
## 3. Shell 与文件操作
|
||
|
||
- 当前默认 Shell 为 PowerShell，使用 PowerShell 语法。
|
||
- 不要通过绝对路径 `cd` 前缀拼接命令；工具支持时优先使用 `workdir`。
|
||
- 子目录操作使用相对路径或直接设置 `workdir`。
|
||
- PowerShell 读取、写入、追加或替换文本时显式指定 UTF-8 编码。
|
||
- 本地文件修改优先使用补丁工具，避免使用不透明的大段覆盖命令。
|
||
- 不执行破坏性删除；如确需删除，先确认精确目标并向用户说明。
|
||
|
||
## 4. 项目目标
|
||
|
||
本项目是一个可在内网部署的 Markdown 排版与 PDF 导出工具，目标包括：
|
||
|
||
- 浏览器选择或编辑 Markdown；
|
||
- 使用服务端统一渲染 Markdown；
|
||
- 网页预览和 PDF 使用同一份 HTML、主题 CSS 与资源；
|
||
- 使用固定版本 Chromium 生成真实、可搜索的 PDF 文件；
|
||
- 支持纸张尺寸、方向、页边距、页眉、页脚和多种页码样式；
|
||
- 支持主题清单与 CSS 主题扩展；
|
||
- 支持 Front Matter、表格、任务列表、脚注、代码高亮、KaTeX、Mermaid 和 ECharts；
|
||
- 提供 Web 与 Electron 桌面端，共用渲染、主题和分页核心；
|
||
- 使用 Docker Compose 在内网部署；
|
||
- 文档只在当前请求中临时处理，不建立文档历史数据库。
|
||
|
||
核心渲染链路：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["Markdown 与资源"] --> B["安全 Markdown 渲染"]
|
||
B --> C["统一 HTML 结构"]
|
||
D["主题 CSS"] --> C
|
||
E["导出配置"] --> C
|
||
C --> F["网页预览"]
|
||
C --> G["Playwright Chromium"]
|
||
G --> H["真实 PDF 文件"]
|
||
```
|
||
|
||
## 5. 技术架构
|
||
|
||
- 前端：React、TypeScript、Vite。
|
||
- 后端：Node.js、TypeScript、Fastify。
|
||
- 桌面端：Electron、electron-builder、NSIS。
|
||
- 应用服务：`packages/application`。
|
||
- 共享模型：`packages/core`。
|
||
- Markdown 渲染：`packages/renderer`。
|
||
- 连续预览与分页引擎：`packages/preview-engine`。
|
||
- ECharts 协议与运行时：`packages/markdown-echarts`。
|
||
- PDF 引擎：Web 使用固定版本 Playwright Chromium，桌面端使用 Electron Chromium。
|
||
- Markdown：markdown-it 及 `@mdit/plugin-*` 插件。
|
||
- 元数据：gray-matter。
|
||
- 安全过滤：sanitize-html。
|
||
- 代码高亮：highlight.js。
|
||
- 数学公式：KaTeX。
|
||
- 图表：Mermaid、ECharts。
|
||
- 校验：Zod。
|
||
- 测试：Vitest。
|
||
- 部署：Docker、Docker Compose。
|
||
|
||
主要目录职责：
|
||
|
||
```text
|
||
apps/web/ 前端编辑、配置与预览界面
|
||
apps/server/ HTTP API、主题读取和 Playwright PDF 服务
|
||
apps/desktop/ Electron 桌面壳、IPC、原生文件与 PDF 能力
|
||
packages/application/ 共享应用服务、主题注册和图片资源处理
|
||
packages/core/ 导出配置和主题清单等共享模型
|
||
packages/renderer/ Markdown 到安全 HTML 的渲染管线
|
||
packages/markdown-echarts/ ECharts YAML 协议、验证和浏览器 SVG 运行时
|
||
packages/preview-engine/ 连续预览、增量分页、媒体适配和 Paged.js 运行时
|
||
themes/ 内置主题
|
||
deploy/ Docker、Compose、Nginx 和部署文档
|
||
docs/ 进度、架构和部署文档
|
||
```
|
||
|
||
## 6. 必须保持的实现约束
|
||
|
||
### 6.1 预览与 PDF 一致性
|
||
|
||
- 预览和 PDF 必须复用 Markdown 渲染结果、`#write` DOM、主题 CSS 和打印 CSS。
|
||
- 不允许前端和 PDF 服务分别维护两套 Markdown 解析逻辑。
|
||
- PDF 使用容器中固定版本的 Chromium，确保不同部署环境结果可复现。
|
||
- Mermaid、字体、图片和公式完成渲染后，才能调用 PDF 输出。
|
||
|
||
### 6.2 主题扩展
|
||
|
||
- 主题通过版本化 `theme.json` 清单接入，不在业务代码中写死主题行为。
|
||
- 主题负责字体、颜色、标题、表格、引用、代码块等视觉样式。
|
||
- 纸张、页边距、页眉页脚、页码和 PDF 元数据属于导出配置，不属于主题。
|
||
- 主题需要声明作者、版本、许可证、DOM 预设和支持能力。
|
||
- Typora 官方默认主题仓库目前没有明确许可证，不得直接复制并打包。
|
||
- 可以自行实现视觉接近的主题，或使用许可证明确允许的第三方主题。
|
||
|
||
### 6.3 安全与隐私
|
||
|
||
- 默认不保存用户 Markdown、图片或生成历史。
|
||
- 资源上传和 PDF 生成使用每请求独立临时目录，并在 `finally` 中清理。
|
||
- 阻止 `../` 路径穿越、任意本地文件读取和符号链接越界。
|
||
- Markdown 原始 HTML 默认不执行；渲染结果必须经过安全过滤。
|
||
- Mermaid 使用严格安全模式。
|
||
- 自定义 CSS、远程图片和远程字体需要限制网络访问，避免信息泄漏和 SSRF。
|
||
- 对 Markdown、资源数量、单文件大小、总大小、渲染时间和 Chromium 并发设置上限。
|
||
|
||
### 6.4 页眉页脚与页码
|
||
|
||
- 普通页眉页脚优先使用 Chromium 的 header/footer template。
|
||
- 模板样式必须内联，不假设继承正文 CSS。
|
||
- 基础页码支持当前页、总页数、中英文组合及左右中位置。
|
||
- 罗马数字、章节页码、封面不计页码等复杂能力放在 PDF 后处理扩展层，不阻塞首版。
|
||
|
||
## 7. 开发和验证
|
||
|
||
要求 Node.js 22 或更高版本。
|
||
|
||
安装依赖：
|
||
|
||
```powershell
|
||
npm install
|
||
```
|
||
|
||
本地开发：
|
||
|
||
```powershell
|
||
npm run dev
|
||
```
|
||
|
||
完整验证：
|
||
|
||
```powershell
|
||
npm test
|
||
npm run typecheck
|
||
npm run build
|
||
```
|
||
|
||
任何功能提交前至少满足：
|
||
|
||
- 相关单元测试通过；
|
||
- 全项目类型检查通过；
|
||
- 生产构建通过；
|
||
- `git diff --check` 无空白错误；
|
||
- 未意外纳入 `node_modules`、`dist`、临时文件或用户文档。
|
||
|
||
如涉及 PDF 输出，还必须使用包含中文、长表格、代码块、公式、Mermaid、图片和分页边界的样例进行端到端验证，并对生成 PDF 做页面渲染检查。
|
||
|
||
## 8. Git 规范
|
||
|
||
- 默认分支为 `main`。
|
||
- 提交前先检查 `git status --short` 和 `git diff`。
|
||
- 不覆盖或混入与当前任务无关的用户修改。
|
||
- 一个提交只表达一个清晰阶段。
|
||
- 提交信息前缀使用标准英文，正文使用简体中文，例如：
|
||
|
||
```text
|
||
feat: 实现网页实时预览
|
||
fix: 修复表格跨页断裂
|
||
docs: 更新内网部署说明
|
||
chore: 初始化项目骨架
|
||
```
|
||
|
||
- 不修改或重写已有提交，除非用户明确要求。
|
||
- 版本标签必须指向专门的发布提交。发布提交信息使用标准英文前缀
|
||
`release:`，简体中文正文必须完整列出该版本的新增能力、问题修复、
|
||
兼容性或部署变化、验证结果和发布产物，不得只写版本号或简略摘要。
|
||
- 版本标签使用 annotated tag；标签说明应与发布提交正文保持一致，完整
|
||
记录本版本更新，不得使用只有版本号的标签说明。
|
||
|
||
## 9. 当前交接入口
|
||
|
||
项目的实时状态、已完成内容、未提交修改和下一步顺序以 `docs/PROGRESS.md` 为准。新会话不得仅凭 Git 提交标题判断进度。
|