Development ZH

开发与发布

文档首页 · English

Node.js 22+：

npm ci
npm test
npm run lint
npm run build
npm run test:electron
npm run check:release

npm ci 仅用于开发/CI，会安装测试用 Electron；用户安装的插件不运行它。npm run dev 监听源码。TypeScript 源码位于 src/，esbuild 将 pdf-lib 和 CSS 后备资源内嵌；构建只需分发 main.js、manifest.json、styles.css。snippets/ 是可选独立布局，examples/ 为合成示例，tests/ 不使用个人笔记。

样式分别维护在 src/styles/callouts.css（数学环境和目录）、src/styles/ui.css（插件界面）、src/styles/document.css（导出排版）和 snippets/academic-layout.css（图表布局）。构建会展开嵌套 CSS，发布样式与导出快照使用同一份编译结果。

原生测试会启动隐藏的独立 Electron 测试窗口，将 README 示意图保存到 screenshots/，将 PDF 和报告保存到 output/。它验证真实 Chromium 打印和样式，不等同于真实 Obsidian 实时预览验收。可将环境变量 ACADEMIC_TEST_THEME 设为本机主题 CSS 路径，额外检查兼容性。完整的证明与注记示例见 examples/proof-and-remark.md。

修改版本时同步 package.json、lockfile、manifest.json、versions.json 和 CHANGELOG。推送与 manifest 版本一致的 tag（例如 2.5.0）后，GitHub Actions 构建、测试并创建草稿 Release，上传三个安装文件；人工审阅后再公开。发布前按 RELEASING.md 核对作者、唯一 ID、实际桌面验收和 Community Directory 扫描。

维护文档

README 保留项目功能概览；安装、语法、设置和排错说明维护在本 Wiki。功能更新时同步修改对应的中英文页面。Wiki 使用独立 Git 仓库：https://github.com/Kristal-Boltinn/academic-notes.wiki.git。

WebKit 与移动端验收

开发依赖增加了 Playwright 和 YAML 测试支持，它们不打包到用户安装的插件中。用 npx playwright install webkit 安装测试浏览器（Linux CI 使用 --with-deps），再运行 npm run test:webkit。独立的合成宿主覆盖横／竖屏视口、原生风格的标题编辑、选区与输入法事件、KP、滚动稳定性以及新增的工作流和交换图操作，不连接真实笔记库。

真实 iPad 验收请用 mobile-acceptance.md。自动化 WebKit 仍不能完整复现 Obsidian WKWebView、屏幕键盘和触摸惯性。

一键部署（2.15.5）

源码仓库放在 vault 外。安装依赖后运行：

npm run deploy -- --vault "测试库路径"

只复制 main.js、manifest.json、styles.css，保留 data.json；旧文件备份在开发仓库的 output/deploy-backups/。Obsidian 已运行、目标库已打开并启用 CLI 时会自动重载；可用 --obsidian 指定 CLI，或 --no-reload 仅安装。可设置本机环境变量 ACADEMIC_NOTES_VAULT 简化为 npm run deploy。