SlideSCI for Mac

这是 SlideSCI 的 Mac PowerPoint Office.js 版本。它是一个独立工程，所有代码都放在 slidesci_for_mac/ 下，不引用 Windows VSTO 工程。

当前功能

• 图片自动排列：列最大宽度、统一高度、统一宽度瀑布流。
• 图片标题：为选中对象添加上标题或下标题。
• 图片标签：支持字母、数字、罗马数字、圆圈数字、中文数字模板。
• 内容插入：Prism 高亮代码块、Markdown 富文本/原生表格/原生公式/引用块、LaTeX 原生公式、LaTeX 图片。
• 格式工具：复制和粘贴中心位置、宽度、高度、文字/填充/边框基础格式。

Markdown 与 LaTeX 验收

test.md 是固定回归样例。把它全文复制到 Markdown 输入框后，应按原文顺序插入标题、普通段落、普通列表、任务列表、表格、数学公式、代码块、引述块和有序列表，直到“归档步骤”结束。任务列表会转换成 ☑ / ☐ 前缀；表格会去掉单元格内的 Markdown 标记；行内公式会保留在同一个文本框中，并由 helper 直接创建为 PowerPoint 原生公式。

表格、代码块、块级公式和引述块会作为独立模块插入。某个模块在当前 PowerPoint API 下失败时，插件会继续插入后续模块，并在状态栏显示失败原因。表格优先使用原生 PowerPoint table：先创建空表格，只传 left/top/width/height，再通过 table cell API 逐格写入内容；如果该路径失败，才尝试 values 参数和文本框网格降级。

块级公式优先通过 helper 生成原生公式；helper 未运行或权限不足时，该公式模块会明确失败，防止把原生公式需求误做成图片。“插入 LaTeX 原生公式”只走 helper；“插入 LaTeX 图片”才使用 MathJax PNG 图片路径。图片插入优先使用矩形图片填充，避免依赖 Mac 端可能不可用的 addPicture preview API；如果图片路径全部不可用，才降级为 LaTeX 源码文本框。选中由本插件插入的公式后点击“读取选中 LaTeX”，会按 tags -> alt text -> localStorage 的顺序回填公式输入框。

如果修改代码后 PowerPoint 里仍显示旧界面，先完全退出 PowerPoint，再清理缓存：

rm -rf ~/Library/Containers/com.microsoft.Powerpoint/Data/Library/Caches/Wef

受 Office.js 能力限制，原生公式依赖本地 helper 和 macOS 自动化权限；导出原图、复制大图、裁剪复制等 Windows VSTO 专属功能暂未实现。

开发

npm install
npm run manifest:dev
npm run dev

默认开发地址是 https://localhost:3000。第一次运行时，先在 Safari 打开 https://localhost:3000 并信任本地开发证书，否则 PowerPoint 可能无法打开任务窗格。

开发模式下，如果要使用 Markdown 行内公式、块级公式或“插入 LaTeX 原生公式”，另开一个终端运行：

npm run helper

helper 监听 http://127.0.0.1:17926，负责通过 PowerPoint 界面自动化创建原生公式对象。安装版默认通过 SlideSCI Companion.app 执行本地 AppleScript；首次使用公式功能时，通常需要在“系统设置 > 隐私与安全性 > 自动化”中允许 SlideSCI Companion.app 控制 System Events，并在“系统设置 > 隐私与安全性 > 辅助功能”中允许 SlideSCI Companion.app 控制电脑。没有辅助功能权限时，公式内容只能以纯文本保留，不能自动转换为 PowerPoint 公式对象。

否则含公式模块会失败并在状态栏显示原因，不会静默降级成图片。

如果你想模拟最终用户的“全本地安装包”运行方式，而不是开发服务器模式，可以先构建前端，再启动本地任务窗格 HTTPS 服务：

npm run build
node scripts/local-addin-server.mjs \
  --root dist \
  --cert ~/Library/Application\ Support/SlideSCI/certs/slidesci-local-cert.pem \
  --key ~/Library/Application\ Support/SlideSCI/certs/slidesci-local-key.pem

安装给最终用户

普通用户推荐直接使用 GitHub Release 安装，不需要先了解仓库结构。当前 release 包是完全本地运行的：

• taskpane 页面来自本机 HTTPS 服务
• 原生公式 helper 来自本机 helper 进程
• 不依赖 GitHub Pages 才能运行

方式 A：从 GitHub Release 安装（推荐）

1. 打开仓库的 Releases 页面 https://github.com/try2love/SlideSCI_for_MAC/releases

2. 下载最新版本里的这一个文件：SlideSCI-for-Mac-vX.Y.Z.zip

   不要下载：

   • Source code (zip)
   • Source code (tar.gz)
   • *.sha256（这个只是校验文件，普通用户可以不下）

3. 如果你的 Mac 还没有安装 Node.js，请先安装 Node.js LTS官方下载页：https://nodejs.org/

   当前版本仍依赖本机 node 来运行本地公式 helper 和本地 taskpane 服务；如果没有 node，安装脚本会退出。

4. 在安装前，先完全退出 Microsoft PowerPoint

5. 双击下载好的 SlideSCI-for-Mac-vX.Y.Z.zip，解压得到一个文件夹

6. 先在终端执行下面的命令，移除 macOS 给下载文件附加的隔离标记。建议先执行这一步，再双击任何 .command 文件，否则 macOS 可能会反复提示“无法打开”或要求去“隐私与安全性”里手动放行：

xattr -dr com.apple.quarantine "/你的解压目录/SlideSCI-for-Mac-vX.Y.Z"

7. 进入解压后的文件夹，双击： install-slidesci-mac.command

   如果仍被阻止：

• 右键该文件，选择“打开”
• 再次点击“打开”

8. 安装脚本会自动完成这些事情：

   • 安装 SlideSCICompanion
   • 复制本地公式 helper
   • 复制本地 taskpane 页面和本地 HTTPS 服务
   • 生成并信任本地 HTTPS 证书
   • 注册 launchd 用户级 LaunchAgent
   • 复制 manifest.xml 到 PowerPoint 的侧载目录

9. 首次使用时，如果系统弹出权限提示，请允许：

   • SlideSCI Companion.app 在“自动化”中控制 System Events
   • 必须在“辅助功能”中允许 SlideSCI Companion.app 控制电脑，否则 Markdown 公式和“插入 LaTeX 原生公式”只能停留为纯文本，不能自动转换为 PowerPoint 原生公式对象

10. 安装完成后，重新打开 PowerPoint

11. 在 PowerPoint 的 “开始” 选项卡中找到 SlideSCI 分组里的 “打开 SlideSCI” 按钮

12. 如果没有直接显示，可以先打开 “加载项”，再选择 SlideSCI

13. 点击后会打开右侧的 SlideSCI 任务窗格

安装完成后的行为：

• 本地 taskpane HTTPS 服务由 companion 保持可用，确保 PowerPoint 能稳定加载插件页面
• PowerPoint 打开时，companion 会自动拉起本地 helper
• PowerPoint 完全退出后，helper 会在短暂宽限期后自动停止
• 不需要再手动运行 npm run helper 或 npm run dev

如果你想不卸载而完全停掉 SlideSCI：

1. 回到解压后的安装包目录
2. 双击 stop-slidesci-mac.command
3. 这会卸载 LaunchAgent，并停止 companion、helper 和本地 taskpane 服务

如果之后想重新启用：

1. 回到解压后的安装包目录
2. 双击 start-slidesci-mac.command

如需卸载：

1. 完全退出 PowerPoint
2. 回到解压后的文件夹
3. 双击 uninstall-slidesci-mac.command
4. 卸载完成后重新打开 PowerPoint

方式 B：从仓库源码安装

如果你不是普通用户，而是想从源码安装或自己修改代码，可以这样做：

1. 把仓库拉到本地：

git clone https://github.com/try2love/SlideSCI_for_MAC.git
cd SlideSCI_for_MAC

2. 安装依赖：

npm install

3. 生成开发用 manifest：

npm run manifest:dev

4. 启动前端开发服务：

npm run dev

5. 另开一个终端，启动公式 helper：

npm run helper

6. 执行本地安装脚本：

npm run install:mac

7. 这个脚本会：
8. 编译本地 SlideSCICompanion watcher
9. 复制 helper 到 ~/Library/Application Support/SlideSCI/
10. 复制本地 taskpane 页面和本地 HTTPS 服务
11. 生成并信任本地 HTTPS 证书
12. 注册 launchd 用户级 LaunchAgent，让 companion 常驻监听 PowerPoint 进程
13. 复制 manifest.xml 到 PowerPoint 的 wef 侧载目录
14. 完全退出并重启 PowerPoint

GitHub 发布

仓库已经加入两条 GitHub Actions 工作流：

• release.yml：当推送 v* tag 时，在 macOS runner 上自动：
  • 构建前端
  • 编译 SlideSCICompanion
  • 渲染面向本地 https://127.0.0.1:18443 的 manifest.xml
  • 打包 release zip
  • 创建 GitHub Release 并上传附件

本地也可以先手动打包预览：

npm run release:package -- v0.1.2

生成物会出现在：

dist/release/

建议的发布流程：

git add .
git commit -m "Prepare release v0.1.2"
git tag v0.1.2
git push origin main --tags

随后 GitHub 会自动：

1. 生成 SlideSCI-for-Mac-v0.1.2.zip
2. 在 Releases 页面创建对应版本并附上安装包

对最终用户来说：

• 只需要下载 SlideSCI-for-Mac-vX.Y.Z.zip
• *.sha256 只是校验文件，可选
• GitHub 自动生成的 Source code 不用于安装

Mac PowerPoint 本地侧载传统 XML manifest：

~/Library/Containers/com.microsoft.Powerpoint/Data/Documents/wef

把 manifest.xml 放入该目录后完全退出并重启 PowerPoint。加载成功后，会在 “开始” 选项卡中出现 SlideSCI 分组和 “打开 SlideSCI” 按钮；如果没有直接显示，也可以从 “加载项” 入口查找 SlideSCI for Mac。点击后会打开右侧任务窗格。

如果加载项不出现：

1. 确认目录是 /Users/<你的用户名>/Library/Containers/com.microsoft.Powerpoint/Data/Documents/wef，不是 iCloud 或项目目录里的 wef。
2. 确认复制的是 manifest.xml 文件本身，不是 slidesci_for_mac 文件夹。
3. 删除旧 manifest 后重新复制新版 manifest.xml，再完全退出 PowerPoint。
4. 清理 Office 缓存后再试：删除 ~/Library/Containers/com.microsoft.Powerpoint/Data/Library/Caches 下的 Office 相关缓存。
5. 如果你使用 release 安装方式，请查看 ~/Library/Application Support/SlideSCI/companion.log，确认本地 taskpane 服务已经启动。
6. 如果你使用源码开发方式，请确认 npm run dev 正在运行，并且 Safari 可以打开 https://localhost:3000/index.html。