193 lines
7.0 KiB
Markdown
193 lines
7.0 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；
|
||
- 使用 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。
|
||
- 共享模型：`packages/core`。
|
||
- Markdown 渲染：`packages/renderer`。
|
||
- PDF 引擎：计划使用 Playwright Chromium。
|
||
- Markdown：markdown-it 及 `@mdit/plugin-*` 插件。
|
||
- 元数据：gray-matter。
|
||
- 安全过滤：sanitize-html。
|
||
- 代码高亮：highlight.js。
|
||
- 数学公式：KaTeX。
|
||
- 图表：Mermaid。
|
||
- 校验：Zod。
|
||
- 测试：Vitest。
|
||
- 部署：Docker、Docker Compose。
|
||
|
||
主要目录职责：
|
||
|
||
```text
|
||
apps/web/ 前端编辑、配置与预览界面
|
||
apps/server/ HTTP API、主题读取及未来 PDF 服务
|
||
packages/core/ 导出配置和主题清单等共享模型
|
||
packages/renderer/ Markdown 到安全 HTML 的渲染管线
|
||
themes/ 内置主题及未来可安装主题
|
||
docker/ 容器化配置
|
||
tests/ 跨包和端到端测试
|
||
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: 初始化项目骨架
|
||
```
|
||
|
||
- 不修改或重写已有提交，除非用户明确要求。
|
||
|
||
## 9. 当前交接入口
|
||
|
||
项目的实时状态、已完成内容、未提交修改和下一步顺序以 `docs/PROGRESS.md` 为准。新会话不得仅凭 Git 提交标题判断进度。
|