openclix-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClix Init

OpenClix 初始化

Purpose

用途

This skill adds OpenClix functionality by copying client code into the user project, not by installing an SDK package.
Use a local-source integration model (shadcn-style): copy, adapt, wire, verify.

本技能通过将客户端代码复制到用户项目中来添加OpenClix功能，而非安装SDK包。采用本地源集成模式（shadcn风格）：复制、适配、关联、验证。

Core Rules

核心规则

Detect the real platform first using project files.
Prioritize minimal edits to existing user code.
Keep all OpenClix files in a dedicated namespace/directory.
When creating local planning/report artifacts under
```
.clix/**
```
, ensure
```
.clix/
```
is listed in
```
.gitignore
```
(add it if missing).
Reuse existing dependencies whenever possible.
Do not add or update dependencies without explicit user approval.
Run a build after integration and fix only integration-caused issues.
Do not use in-memory fallback in production integration paths.

首先通过项目文件检测实际的运行平台。
优先对现有用户代码做最小程度的修改。
所有OpenClix文件都存放在专属的命名空间/目录下。
在
```
.clix/**
```
下生成本地规划/报告产物时，确保
```
.clix/
```
已被列入
```
.gitignore
```
（如果不存在则主动添加）。
尽可能复用现有依赖。
未经用户明确批准，不得新增或更新依赖。
集成完成后运行构建，仅修复由集成导致的问题。
生产环境的集成路径中不得使用内存兜底方案。

Platform Detection

平台检测

Use file evidence in this order:


app.json
package.json
pubspec.yaml
*.xcodeproj
build.gradle

Priority	Platform	Required Evidence
1	Expo	`app.json` or `app.config.*` with `expo`
2	React Native	`package.json` with `react-native` and typical `ios/` + `android/` structure
3	Flutter	`pubspec.yaml` with Flutter SDK
4	iOS native	`.xcodeproj` or `.xcworkspace` or `Package.swift`
5	Android native	`build.gradle` or `build.gradle.kts`

If signals conflict, trust concrete file evidence and report the mismatch.

按以下优先级通过文件特征判断：


expo
react-native
pubspec.yaml
*.xcodeproj
build.gradle

优先级	平台	所需依据
1	Expo	包含 `expo` 配置的 `app.json` 或 `app.config.*` 文件
2	React Native	包含 `react-native` 依赖的 `package.json` ，以及典型的 `ios/` + `android/` 目录结构
3	Flutter	包含Flutter SDK配置的 `pubspec.yaml`
4	iOS原生	`.xcodeproj` 、 `.xcworkspace` 或 `Package.swift` 文件
5	Android原生	`build.gradle` 或 `build.gradle.kts` 文件

如果信号存在冲突，以实际文件特征为准并报告不一致问题。

Template Selection

模板选择

Expo / React Native:
```
templates/react-native/
```
Flutter:
```
templates/flutter/
```
iOS:
```
templates/ios/
```
Android:
```
templates/android/
```
(package namespace
```
ai.openclix.*
```
)

templates/react-native/

is the canonical reference when platform ports need alignment.

Expo / React Native:
```
templates/react-native/
```
Flutter:
```
templates/flutter/
```
iOS:
```
templates/ios/
```
Android:
```
templates/android/
```
（包命名空间为
```
ai.openclix.*
```
）

当不同平台的移植需要对齐时，

templates/react-native/

是官方参考标准。

Integration Workflow

集成工作流

Identify platform and current startup/event/lifecycle entry points.
Copy the selected template into a dedicated OpenClix area in the user project.
Wire only required touchpoints:
- initialization at app startup
- event tracking call path
- foreground/app lifecycle trigger
Keep existing architecture and code style intact; avoid broad refactors.
Validate against
```
references/openclix.schema.json
```
when config/schema changes are involved.

识别平台以及当前项目的启动/事件/生命周期入口点。
将选中的模板复制到用户项目中专属的OpenClix目录下。
仅关联必要的接入点：
- 应用启动时的初始化逻辑
- 事件埋点调用路径
- 前台/应用生命周期触发逻辑
保留原有架构和代码风格不变，避免大范围重构。
涉及配置/ schema变更时，对照
```
references/openclix.schema.json
```
进行校验。

Adapter Selection Rules

适配器选择规则

Select adapters using existing dependencies only:

Choose concrete adapters at integration time; avoid runtime dependency auto-detection.
If the project already has a supported persistent storage dependency, wire that implementation.
If notification libraries already exist, wire the matching scheduler adapter.
If no compatible dependency exists, fail fast with a clear integration error.
Keep degraded in-memory paths out of production template defaults.

React Native / Expo storage selection:

AsyncStorage project: use
```
AsyncStorageCampaignStateRepository
```
.
MMKV project: use
```
MmkvCampaignStateRepository
```
.
If both exist, prefer the project standard and copy only one storage adapter into the app.

Inject

campaignStateRepository

explicitly when calling

Clix.initialize(...)

React Native / Expo scheduler selection:

Notifee project: create
```
new NotifeeScheduler(notifee)
```
.

Expo notifications project: create

new ExpoNotificationScheduler(ExpoNotifications)

Inject
```
messageScheduler
```
explicitly when calling
```
Clix.initialize(...)
```
.

Platform expectations:

React Native / Expo:
- Do not use runtime adapter auto-detection in
```
Clix
```
  core.
- Select storage/scheduler implementations during integration and inject dependencies explicitly.
- If compatible implementations are unavailable, initialization must fail with clear instructions.
Flutter:
- Use callback-based scheduler adapter for existing notification plugin
- Require an explicit scheduler and state repository dependency at initialization
iOS / Android native:
- Use platform-native implementations by default
- Do not introduce in-memory/no-op fallback as the default runtime behavior

仅基于现有依赖选择适配器：

集成时选择具体的适配器，避免运行时依赖自动检测。
如果项目已经存在支持的持久化存储依赖，关联对应的实现。
如果已经存在通知库，关联匹配的调度器适配器。
如果不存在兼容的依赖，快速抛出明确的集成错误。
生产模板默认不要包含降级的内存运行方案。

React Native / Expo 存储选择：

使用AsyncStorage的项目：使用
```
AsyncStorageCampaignStateRepository
```
。
使用MMKV的项目：使用
```
MmkvCampaignStateRepository
```
。
如果两者都存在，优先选择项目标准方案，仅复制一个存储适配器到应用中。

调用

Clix.initialize(...)

时显式注入

campaignStateRepository

。

React Native / Expo 调度器选择：

使用Notifee的项目：创建
```
new NotifeeScheduler(notifee)
```
。

使用Expo通知的项目：创建

new ExpoNotificationScheduler(ExpoNotifications)

。

调用
```
Clix.initialize(...)
```
时显式注入
```
messageScheduler
```
。

平台要求：

React Native / Expo:
- 不要在
```
Clix
```
  核心中使用运行时适配器自动检测。
- 集成阶段选择存储/调度器实现，显式注入依赖。
- 如果没有可用的兼容实现，初始化必须失败并给出明确指引。
Flutter:
- 为现有通知插件使用基于回调的调度器适配器
- 初始化时要求显式传入调度器和状态仓库依赖
iOS / Android原生:
- 默认使用平台原生实现
- 不要将内存/空操作兜底作为默认运行时行为

Notification Permission and Foreground Setup

通知权限与前台设置

Notification permission must be requested before campaign triggers fire. Each platform template includes a permission utility; the integration agent must wire it at the appropriate location in the host app.

必须在活动触发前申请通知权限。每个平台模板都包含权限工具，集成Agent必须将其关联到宿主应用的合适位置。

React Native / Expo — Permission

React Native / Expo — 权限

Notifee projects: Import
```
requestNotifeePermission
```
from
```
infrastructure/NotifeeNotificationSetup
```
. Call it at app startup (e.g. in
```
App.tsx
```
or a startup hook) passing the Notifee adapter. No foreground handler is needed — Notifee handles foreground display natively via
```
presentationOptions
```
.

Expo projects: Import

requestExpoPermission

and

setupExpoForegroundHandler

from

infrastructure/ExpoNotificationSetup

. Call

setupExpoForegroundHandler

once during initialization, then call

requestExpoPermission

at app startup.

Notifee项目： 从
```
infrastructure/NotifeeNotificationSetup
```
导入
```
requestNotifeePermission
```
。在应用启动时调用（例如在
```
App.tsx
```
或者启动钩子中），传入Notifee适配器。不需要前台处理程序——Notifee通过
```
presentationOptions
```
原生处理前台展示。

Expo项目： 从

infrastructure/ExpoNotificationSetup

导入

requestExpoPermission

和

setupExpoForegroundHandler

。初始化时调用一次

setupExpoForegroundHandler

，然后在应用启动时调用

requestExpoPermission

。

iOS — Permission and Foreground Display

iOS — 权限与前台展示

Permission: Call

await NotificationPermission.request()

at app startup (e.g. in

application(_:didFinishLaunchingWithOptions:)

or a SwiftUI

.task

modifier). This calls

UNUserNotificationCenter.requestAuthorization

Foreground display: iOS suppresses notification banners when the app is active. The template provides
```
ForegroundNotificationHandler.handleWillPresent(notification:completionHandler:)
```
as a static method.
- Critical: iOS allows only ONE
```
UNUserNotificationCenterDelegate
```
  per app. Do NOT assign
```
ForegroundNotificationHandler
```
  as the delegate. Instead, set the app's existing delegate (usually
```
AppDelegate
```
  ) as
```
UNUserNotificationCenter.current().delegate = self
```
  , and call the static method from the delegate's
```
willPresent
```
  implementation.

权限： 在应用启动时调用

await NotificationPermission.request()

（例如在

application(_:didFinishLaunchingWithOptions:)

或者SwiftUI的

.task

修饰符中）。该方法会调用

UNUserNotificationCenter.requestAuthorization

。

前台展示： 应用处于活跃状态时iOS会默认隐藏通知横幅。模板提供了静态方法
```
ForegroundNotificationHandler.handleWillPresent(notification:completionHandler:)
```
。
- 重要提示： iOS每个应用仅允许存在一个
```
UNUserNotificationCenterDelegate
```
  。不要将
```
ForegroundNotificationHandler
```
  设置为代理，而是将应用现有代理（通常是
```
AppDelegate
```
  ）设置为
```
UNUserNotificationCenter.current().delegate = self
```
  ，并在代理的
```
willPresent
```
  实现中调用该静态方法。

Android — Permission

Android — 权限

Manifest: Add

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

AndroidManifest.xml

Runtime request: On API 33+ (Android 13), call

NotificationPermission.shouldRequestPermission(context)

at startup. If it returns

true

, use the Activity's

requestPermissions()

ActivityResultLauncher

to request

NotificationPermission.getPermissionString()

Android does NOT need foreground display setup —
```
NotificationManager.notify()
```
always displays regardless of app state.

清单配置： 向

AndroidManifest.xml

添加

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

。

运行时申请： 在API 33+（Android 13）设备上，启动时调用

NotificationPermission.shouldRequestPermission(context)

。如果返回

true

，使用Activity的

requestPermissions()

或

ActivityResultLauncher

申请

NotificationPermission.getPermissionString()

。

Android不需要前台展示设置——无论应用处于什么状态，
```
NotificationManager.notify()
```
都会正常展示通知。

Flutter — Permission and Foreground Display

Flutter — 权限与前台展示

The

NotificationPermission

class in

notification/notification_permission.dart

accepts callbacks. Wire the host app's notification plugin:

Provide a
```
requestPermission
```
callback that calls the plugin's permission request API.
Provide a
```
checkPermissionStatus
```
callback that checks current status.
Optionally provide a
```
setupForegroundHandler
```
callback to configure foreground display (required for iOS, not needed for Android).
Call
```
permission.request()
```
at app startup before campaign triggers fire.
Call
```
permission.setupForeground()
```
during initialization if the handler is provided.

notification/notification_permission.dart

中的

NotificationPermission

类支持传入回调。关联宿主应用的通知插件：

提供
```
requestPermission
```
回调，调用插件的权限申请API。
提供
```
checkPermissionStatus
```
回调，检查当前权限状态。
可选提供
```
setupForegroundHandler
```
回调配置前台展示（iOS需要，Android不需要）。
应用启动时、活动触发前调用
```
permission.request()
```
。
如果提供了处理程序，初始化时调用
```
permission.setupForeground()
```
。

Directory and Namespace Policy

目录与命名空间规则

OpenClix files must stay grouped in a dedicated location:

React Native / Expo:
```
src/openclix/
```
Flutter:
```
lib/openclix/
```
iOS:
```
OpenClix/
```
or
```
Sources/OpenClix/
```

Android:

app/src/main/kotlin/ai/openclix/

with

ai.openclix.*

packages

OpenClix文件必须统一存放在专属位置：

React Native / Expo:
```
src/openclix/
```
Flutter:
```
lib/openclix/
```
iOS:
```
OpenClix/
```
或
```
Sources/OpenClix/
```

Android:

app/src/main/kotlin/ai/openclix/

，使用

ai.openclix.*

包名

Dependency Policy

依赖规则

Before changing dependencies:

Check what the selected template expects.
Check what the user project already has.
Prefer existing project libraries or platform APIs.
If replacement is possible, adapt template code instead of adding dependencies.
If no safe replacement exists, ask for approval before any dependency add/update.

Never run package-manager install/update commands without approval.

修改依赖前：

检查选中的模板需要哪些依赖。
检查用户项目已经存在哪些依赖。
优先使用项目已有库或者平台API。
如果可以替换，调整模板代码而非新增依赖。
如果没有安全的替换方案，新增/更新依赖前必须申请用户批准。

未经批准绝对不要运行包管理器的安装/更新命令。

Build Verification

构建验证

After wiring, run platform-appropriate build/analysis commands based on detected project structure. Prefer project-native commands first (existing scripts, Gradle tasks, Xcode scheme, Flutter workflow).

If unclear, use common fallback commands:

React Native / Expo:
```
npx tsc --noEmit
```
Android:
```
./gradlew assembleDebug
```

iOS:

xcodebuild -scheme <scheme> build

swift build

Flutter:
```
flutter analyze
```

If build fails, apply minimal targeted fixes and retry. Stop only on hard blockers.

关联完成后，基于检测到的项目结构运行对应平台的构建/分析命令。优先使用项目原生命令（现有脚本、Gradle任务、Xcode scheme、Flutter工作流）。

如果不明确，使用通用 fallback 命令：

React Native / Expo:
```
npx tsc --noEmit
```
Android:
```
./gradlew assembleDebug
```

iOS:

xcodebuild -scheme <scheme> build

或

swift build

Flutter:
```
flutter analyze
```

如果构建失败，做最小化的定向修复后重试，仅遇到无法解决的阻塞问题时才停止。

Completion Checklist

完成检查清单

OpenClix code added under dedicated namespace/directory.
Existing app code changes are minimal and localized.
No unapproved dependency additions or upgrades.
Adapter wiring prefers existing dependencies and fails fast when unavailable.
Build verification executed.
Any remaining blockers clearly reported.

OpenClix代码已添加到专属的命名空间/目录下。
对现有应用代码的修改是最小化且局部的。
没有未经批准的依赖新增或升级。
适配器关联优先使用现有依赖，不存在兼容依赖时会快速报错。
已执行构建验证。
所有剩余阻塞问题都已明确上报。