离线占卜 App 构建

做一个断网可用、数据不出手机、可商用闭源的占卜类 App。核心不是"调用某个占卜 API"，而是把占卜拆成两层：可离线计算的确定性层（抽牌、排盘、历法）与可离线运行的解读层（静态文案库 + 规则引擎）。云端 AI 只做可选的锦上添花，绝不能成为主链路依赖。

何时用这个 skill

触发场景：

• 「做一个塔罗占卜 App」「开发一个占卜工具」「合作/感情合盘工具」
• 「能不能离线运行」「飞行模式也要能用」「数据不要上传」
• 「帮我打包成手机上能装的 App」，且内容属占卜、命理、运势、合盘类

不适用：需要实时行情/联网数据的应用；纯占卜文案创作（不涉及工程实现）；已有 App 只改一处 UI。

五步工作流

按顺序走，每一步都有明确的产出物。跳步会在后面付出更大代价。

第 1 步：先定形态与解读层，别急着写代码

必须与用户确认两件事，缺一不可：

把这两条写进对话确认后再动手。用户若说"要真正的 AI 智能解读"，要如实说明：离线与"通用大模型级智能"不可兼得，只能规则兜底 + 联网增强。

第 2 步：查依赖许可证（这一步能救整个产品）

在 npm install 之前，逐个核查：

npm view <包名> version license dependencies

凡是 AGPL / GPL，一律不引入闭源分发的 App。 详见 references/licensing.md（含真实踩坑案例与 MIT 白名单）。

第 3 步：搭四层结构

assets/
├── js/vendor/     第三方库本地化（复制进仓库，不用 CDN）
├── js/data/       静态数据层：牌库、牌阵、五行表
├── js/engine/     纯函数引擎：抽牌、解读、评分、动效
└── js/ai/         可选增强层（未配置时必须静默降级）

铁律：vendor 里的库必须是本地文件。任何 https://cdn... 引用都会让"离线"变成假离线。细节见 references/architecture.md。

第 4 步：写数据层与规则引擎

占卜的"智能"来自数据颗粒度，不是算法复杂度。牌库字段设计、牌阵定义、评分规则、文案组合逻辑，见：

• references/tarot-engine.md —— 78 张牌数据结构、正逆位、牌阵与评分规则
• references/bazi-wuxing.md —— 用 lunar-javascript 本地算日主五行与生克

关键设计原则：每张牌的合作/关系场景含义单独一个字段。只写通用牌义，解读会像百度百科；写了场景含义，才会像"懂这段关系"。

第 5 步：离线体检 + 打包

先用脚本体检，再打包：

python scripts/check_offline.py <项目目录>          # 离线合规体检，必须全绿
python scripts/scaffold.py <目标目录> --title 我的占卜  # 需要骨架时才用

体检会拦：外部 URL / CDN 引用、node_modules 混入产物、AGPL 依赖、缺失的本地 vendor、隐私风险写法。

打包 Capacitor 流程、构建脚本坑位，见 references/packaging.md。

三条不可妥协的红线

1. 许可证：AGPL 不进闭源 App。宁可自己写算法，也不引入传染性许可证。
2. 零外链：产物目录里不允许出现任何远程 URL。构建脚本应主动扫描并拦截。
3. 离线优先降级：联网模块未配置、断网、接口报错时，必须静默走本地规则，绝不阻塞主流程、绝不弹错误。

常见翻车点

参考文件

脚本

两个脚本都支持 --help，纯标准库，无需安装依赖。