SuperAPI AI 工具集

arrow-js-obsidian-porting

编程与开发

查看项目

更新于 10-15 23:48

技能介绍

用途:在 Arrow 组件的沙箱开发与 Obsidian 插件间做移植对齐。沙箱是组件的唯一真源,插件获得近乎逐字一致的副本,主要风险是手工改动插件副本导致漂移,因此对组件可移植正文做内容寻址,用规范化哈希在两端比对,思路等同“不要手工修改生成产物”。

主要能力:scripts/component-hash.mjs 为无依赖 Node 工具,规范化逻辑在 scripts/lib/canonical-source.mjs。用法:node scripts/component-hash.mjs <file> 打印规范哈希;--verify <sandbox> <plugin> 输出 PARITY OK 或 DRIFT(退出码 0/1);--check port-parity.json 批量检查,漂移时退出 1;--check port-parity.json --update 重新确认基线。规范化规则:剥离 import 语句、换行统一为 \n、去行尾空白、折叠连续空行、保留注释,再取 SHA-256,因此仅 import 或格式差异哈希相同,正文/模板/注释变更即视为漂移。port-parity.json 按文件所在位置解析路径,可记录 sandbox 路径与回退 hash。

使用方式:把两个无依赖文件复制进插件仓库,配置清单后在 husky pre-commit 与 CI 运行 node scripts/component-hash.mjs --check port-parity.json;漂移时提交失败,应改沙箱组件后重新移植,不要手改副本,仅在有意的重新移植后用 --update。需同步复制 src/utilities.css(oas-- 前缀的布局、间距、排版、边框工具类,含 4px 主刻度与 2px 子刻度,按 Obsidian 令牌命名),每个插件复制一次并由所有移植组件共用;沙箱新增工具类需重新复制。移植组件应通过 props/getter 取数据,把数据源接线放在 main.ts 或 ItemView.onOpen(),尽量不在组件正文内调用 Obsidian API。

CSS 移植:pnpm port:css 依据 porting.config.json(cssPrefix、viewSubScope、include、outDir)为类选择器加前缀,源文件不被修改;viewSubScope 为 src/views/<ViewName>/ 下的 CSS 增加祖先选择器以避免跨视图样式泄漏,需在 ItemView.onOpen() 给视图根元素加对应类。该命令是移植前的最后一步,不属于 pnpm ci。

限制:不做 Obsidian 运行时组件 DOM 哈希,因为沙箱与真实环境 DOM 本身不同;运行时视觉/CSS 风险需在 Obsidian 中实际加载查看。规划中的样式新鲜度检查(比对 Obsidian 令牌与沙箱 app.css 快照)尚未实现。