thierryc/glyphs3-to-glyphs4-skill

将 Glyphs 3 插件迁移至 Glyphs 4

创建一个可供审查的 Python 插件迁移副本。将静态迁移视为在 Glyphs 4 中进行手动启动测试的准备步骤，而非运行时兼容性的证明。

防护措施

• 保留原始插件或仓库。
• 绝不在原地迁移。如果输出路径已存在，则拒绝执行。
• 除非用户另行请求，否则绝不安装、执行、重载、重新启动 Glyphs，或更改实时的 Plugins 文件夹。
• 使用 Glyphs MCP docs_search 和 docs_get 工具作为主要的开发知识库。工具命名空间因客户端而异；通过它们的最终工具名称和描述来解析它们。
• 在更改 GlyphsApp API、插件生命周期方法、选择器、回调、捆绑元数据或形状处理之前，先获取聚焦的官方指南。
• 正常工作时不要调用 docs_enable_page_resources。按需检索页面。
• 优先使用 schriftgestalt/GlyphsSDK 的当前 Glyphs4 分支；不要假定 Glyphs 3 模板或缓存加载器是最新的。
• 将行为更改与机械性迁移更改分开。

Glyphs MCP 知识库工作流程

在审查特定 API 的发现之前，请阅读 references/glyphs-mcp-development-kb.md。

1. 确认可以从 Glyphs MCP 服务器获取 docs_search 和 docs_get 工具。
2. 在编辑前建立文档基线：
   • 搜索 plugins 并获取官方插件手册结果。
   • 搜索 Info.plist 并获取 Python 插件模板概览和 plist 模板。
   • 搜索确切的基类，例如 GeneralPlugin、ReporterPlugin、FilterWithoutDialog、PalettePlugin、SelectTool 或 FileFormatPlugin；获取其指南、源模板以及相关的插件 API 部分。
3. 分别搜索每个不熟悉的类、属性、回调或选择器。优先使用简短的确切符号，例如 GSLayer、shapes 或 addCallback。
4. 通过返回的 doc_id 或 path 获取结果。如果 truncated 为 true，则从 nextOffset 继续，直到相关部分完整。
5. 记录每个获取的页面的标题、docId、sourceKind、sourceUrl 以及它支持的迁移决策。将此证据包含在交接文档中。
6. 如果工具不可用，报告 Glyphs MCP 文档审查被阻止。可以继续进行静态审计，但不要将未经验证的 API 或生命周期更改呈现为可迁移的。

工作流程

1. 解析源插件或仓库、预期的兼容性目标（仅 Glyphs 4 或 Glyphs 3 和 4）以及一个新的输出路径。

2. 连接到 Glyphs MCP 开发知识库，并为检测到的插件系列获取基线页面。

3. 获取或定位官方 GlyphsSDK Glyphs4 分支的当前检出副本。

4. 复制前进行审计：

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --sdk "/path/to/GlyphsSDK"
   

5. 阅读 references/migration-review.md。对于每个特定 API 的发现，在捆绑的 Glyphs 文档中搜索该类、属性、回调、选择器或插件类型，并仅获取相关页面。

6. 创建迁移副本并应用保守的框架导入修复：

   python3 scripts/migrate_plugin.py "/path/to/source" \
     --output "/path/to/new-glyphs4-copy" \
     --sdk "/path/to/GlyphsSDK" \
     --apply-safe-fixes
   

7. 仅审查影响后使用可选重写：

   • 添加 --rewrite-wildcard-imports 以使用在 Glyphs 4 .pyi 存根中找到的符号替换简单的 from GlyphsApp import * 语句。
   • 添加 --replace-loader 以将 SDK 模板的 Contents/MacOS/plugin 复制到每个 bundle 中。
   • 添加 --align-glyphs4-plist 以删除当前 Glyphs 4 模板中不存在的旧版更新馈送键。首先确认插件不依赖于其自身的更新馈送。

8. 审查生成的迁移报告和完整的源代码差异。手动修复生命周期、API、依赖、UI 或混合形状方面的问题。将每个特定的 API 更改与获取的知识库页面相关联。

9. 验证每个 bundle：

   • 使用目标 Glyphs Python 版本解析所有 Python 文件。
   • 在每个 Contents/Info.plist 上运行 plutil -lint。
   • 确认 NSPrincipalClass、PyMainFileNames 和主 Python 类一致。
   • 将 bundle 结构与匹配的当前 Glyphs 4 SDK 模板进行比较。
   • 当界面发生更改时，重新编译 .xib 文件。

10. 交接一个手动测试计划。在 Glyphs 4 中测试一个可丢弃的副本，执行每个菜单项和回调，检查宏面板和控制台输出，并测试与插件相关的撤销、导出、绘制和依赖路径。

兼容性决策

• 对于 仅 Glyphs 4，在当前的存根中确认后，允许 Glyphs 4 运行时支持的 API 和 Python 语法。
• 对于 Glyphs 3 和 4，在实用时保持共享代码路径，使用能力检查来处理真正的 API 差异，并测试两个应用程序。不要仅仅为了注解而添加仅 Glyphs 4 的语法。
• 如果插件重组了 layer.paths、layer.components 或 layer.shapes，检查它是否必须保留混合形状顺序或更新的形状种类。永远不要推断仅路径的重写是无损的。

交付物

返回新副本、迁移报告、兼容性目标、静态验证结果和剩余的手动 Glyphs 4 测试。包含一个文档证据表，其中包含每个页面的标题、Glyphs MCP docId、官方 sourceUrl 以及它支持的决策。明确说明没有进行实机安装或运行时测试，除非确实进行了。

资源

• scripts/migrate_plugin.py：审计和非破坏性副本辅助工具。
• references/migration-review.md：基于证据的审查清单和升级点。
• references/glyphs-mcp-development-kb.md：确切的 MCP 查找、分页、证据和恢复协议。
• .mcp.json：Claude Code 插件与本地 Glyphs MCP 服务器的连接。
• mcp.json：Cursor 插件与本地 Glyphs MCP 服务器的连接。
• .claude-plugin/plugin.json：Claude Code 社区/插件元数据；使用 claude --plugin-dir 加载此文件夹。
• .cursor-plugin/plugin.json：Cursor 插件元数据，注册根 SKILL.md 和 mcp.json。
• agents/openai.yaml：Codex 显示元数据和 Glyphs MCP 依赖项。