# OpenClix 活动设计将活动目标转化为架构有效的 OpenClix 配置 JSON，并尽可能减少歧义。保持输出可审核并与 OpenClix 运行时合约兼容。当用户请求实现时，将最终的配置 JSON 安装到应用程序资源中并连接运行时初始化代码。 ## 工作流程按顺序执行这些阶段。 1. 收集活动背景。 2. 构建或刷新应用程序配置文件工件。 3.设计活动集。 4. 生成或更新 OpenClix 配置。 5. 验证工件输出。 6. 检查现有的 OpenClix 集成并选择交付模式。 7. 执行选定的交付路径并移交。仓库卫生规则： * 在 `.openclix/**` 下写入输出之前，请确保 `.openclix/` 已在 `.gitignore` 中列出（如果缺少，请添加）。 ## 1) 收集活动背景仅收集设计决策所需的缺失事实： * 应用程序名称和平台 * 主要保留目标（入职、习惯、重新参与、里程碑、功能发现） * 事件分类：事件名称+可用的属性键 * 当前活动配置路径（如果存在） * JSON 资产的现有应用程序资源/文件管理约定 * OpenClix当前初始化（或应该初始化）的启动位置 * 代码中当前引用的确切运行时捆绑配置加载路径和文件名（区分大小写） * 用户拥有的 HTTP 服务器/托管配置的部署目标（如果需要远程服务） * 全局限制：安静时间、频率上限预期、区域设置/时区假设如果用户已经提供了足够的详细信息，请不要重新询问已解决的问题。 ## 2) 构建或刷新应用程序配置文件工件在创作营销活动之前： * 阅读 `references/json-schemas.md`。 * 阅读 `references/schemas/app-profile.schema.json`。 * 创建或更新 `.openclix/campaigns/app-profile.json`。 * 捕获目标、事件分类、个性化变量、现有活动和约束。 * 在继续之前提供 JSON 并确认准确性。 ## 3) 设计活动集在起草活动之前： * 阅读 `references/openclix-campaign-playbook.md`。设计 3-5 个营销活动，除非用户请求不同的计数。跨生命周期阶段或明确的用户优先级传播活动。 OpenClix建模规则： * 一项活动传达一条信息。 * 将多步骤旅程建模为多个相关的营销活动 ID（例如“onboarding-step-1”、“onboarding-step-2”、“onboarding-step-3”）。触发选择规则： * 使用“事件”进行行为驱动的消息传递。 * 使用“预定”进行一次性日期/时间交付。 * 使用“recurring”来重复节奏。抑制和取消规则： * 当行为可能使意图无效时，使用 `delay_seconds` \+ `cancel_event` 来取消挂起的注册。 * 需要时使用全局 `settings.do_not_disturb` 和 `settings.Frequency_cap`。内容规则： * 仅使用具有“{{key}}”语法的已知个性化密钥。 * 保持模式安全限制：标题 <= 120，正文 <= 500。 * 优先选择简洁的 UX 文案（标题 <= 45，正文 <= 140），除非用户需要更长的文案。功能覆盖规则（添加新营销活动时强制执行）： * 针对 `references/schemas/openclix.schema.json` 运行功能传递并显式评估每个可配置杠杆： * 全局: `settings.Frequency_cap`, `settings.do_not_disturb` * 活动：`频率上限` * 事件触发：`delay_seconds`、`cancel_event` * 重复触发：`start_at`、`end_at`、`rule.interval`、`weekly_rule.days_of_week`、`time_of_day` * 消息内容：`image_url`、`landing_url`、个性化占位符 * 应用与活动目标相关的每一个杠杆；如果不使用杠杆，请在切换假设中说明原因。 ## 4) 生成或更新 OpenClix 配置在编写配置之前： * 阅读 `references/schemas/openclix.schema.json`。按以下顺序写入更新： 1. 更新用户指定的配置路径（如果提供）。 2. 否则写入 `.openclix/campaigns/openclix-config.json`。远程送货注意事项： * 生成的相同配置 JSON 可以上传到 Web 服务器并通过 HTTPS 提供服务以进行远程访问。 * 对本地资源交付和远程端点交付使用相同的架构有效的 JSON 工件。 * 外部验证器的公共模式参考：`https://openclix.ai/schemas/openclix.schema.json`。保证这些不变量： * `"$schema"` 正是 `https://openclix.ai/schemas/openclix.schema.json`。 * `schema_version` 正是 `openclix/config/v1`。 * `config_version` 是明确且可追踪的。 * 活动 ID 为短横线大小写。 * 活动“类型”为“活动”。 * 活动“状态”为“正在运行”或“已暂停”。 * 存在特定于触发器的必填字段。 * 有意评估可选但可用的字段（默认情况下不忽略），特别是频次上限和抑制控制。 * 没有引入未知字段。编辑现有配置时，尽量减少差异并保留不相关的活动。 ## 5) 验证工件输出验证是强制性的。在继续交付之前修复所有故障。 ### 配置验证主要路径（在 openclix 存储库内）： * `./scripts/validate_config.sh <配置文件>` 这会一次性运行 JSON 语法、ajv-cli 模式验证 (`--spec=draft2020`) 和结构抽查。所有检查都必须通过。后备路径（在存储库之外或当脚本不可用时）： 1.`jq. ` — 验证 JSON 语法。 2. 使用 `ajv` 根据规范模式进行验证： * 如果您位于 `openclix` 存储库中（在本地签出架构）： `npx --yes -p ajv-cli@5.0.0 -p ajv-formats@3.0.1 ajv validate --spec=draft2020 -c ajv-formats -s ./references/schemas/openclix.schema.json -d ` * 如果您位于存储库之外（无本地模式），请使用已发布的规范模式 URL：`npx --yes -p ajv-cli@5.0.0 -p ajv-formats@3.0.1 ajv validate --spec=draft2020 -c ajv-formats -s https://openclix.ai/schemas/openclix.schema.json -d ` 3. 手动验证：`$schema`是`https://openclix.ai/schemas/openclix.schema.json`，`schema_version`是`openclix/config/v1`，campaign键是短横线，每个campaign都有`type: "campaign"`，每个`trigger.type`值都有其匹配的子对象键。 ### 应用程序配置文件验证根据本地或发布的架构验证应用程序配置文件工件： * 本地（在 `openclix` 存储库内）：`references/schemas/app-profile.schema.json` * 发布：`https://openclix.ai/schemas/app-profile.schema.json` * 命令（根据可用性选择一个）： * 本地架构：`npx --yes -p ajv-cli@5.0.0 -p ajv-formats@3.0.1 ajv validate --spec=draft2020 -c ajv-formats -s ./references/schemas/app-profile.schema.json -d ` * 已发布架构：`npx --yes -p ajv-cli@5.0.0 -p ajv-formats@3.0.1 ajv validate --spec=draft2020 -c ajv-formats -s https://openclix.ai/schemas/app-profile.schema.json -d ` ### 移交报告交接时报告： * 输出文件路径 * 活动 ID 和意图 * 配置验证结果：通过或失败（有详细信息） * 应用程序配置文件验证结果：通过或失败（包含详细信息） * 关键假设 * 需要用户输入的未解决的差距 ## 6) 检查现有 OpenClix 集成并选择交付模式生成配置 JSON 后，在做出交付决策之前检查现有的 OpenClix 集成代码。检查清单： * 找到 `OpenClix.initialize(...)` 调用站点和当前的 `OpenClixConfig.endpoint` 使用情况。 * 找到任何现有的“OpenClixCampaignManager.replaceConfig(...)”用法。 * 确认当前启动接线使用的项目资源约定。 * 如果 OpenClix 客户端集成缺失，请首先运行 `openclix-init` 并使用其检测到的平台/启动/资源约定。决策门（强制，除非用户已经指定模式）： * 询问用户使用哪种交付方式： 1. 在应用程序包中捆绑配置。 2. 上传到用户现有的HTTP 服务器并通过HTTPS 提供服务。 * 当用户没有选择一种交付模式时，不要假设交付模式。 ## 7) 执行选定的交付路径并移交 ### A) 捆绑应用内（本地资源交付）当用户选择捆绑模式时： 1. 使用从现有代码和 `openclix-init` 输出中发现的平台/启动/资源信息。 2. 按以下顺序解析运行时包目标路径： * 使用代码中已引用的确切现有加载路径。 * 如果尚不存在加载路径，则使用后备默认值： * React Native / Expo：`assets/openclix/openclix-config.json` * Flutter: `assets/openclix/openclix-config.json` （并在 `pubspec.yaml` 中注册） * iOS：`/OpenClix/openclix-config.json`（添加到复制捆绑资源） * Android: `app/src/main/assets/openclix/openclix-config.json` 3. 将 `.openclix/campaigns/openclix-config.json` 复制到已解析的运行时路径。 4. 将文件名保留为小写“openclix-config.json”，除非项目已经具有不同的运行时文件名和加载器引用。 5. 将“OpenClixConfig.endpoint”设置为运行时加载程序使用的相同捆绑路径标识符。 6. 更新启动代码以从确切的捆绑路径加载 JSON，解析“Config”，然后在初始化后调用“OpenClixCampaignManager.replaceConfig(...)”。 7. 接线后运行平台构建/分析检查。 8. 执行奇偶校验：复制的文件路径、加载器路径引用和“OpenClixConfig.endpoint”标识符必须全部匹配。 ### B) 托管 HTTP 交付（用户拥有的服务器）当用户选择HTTP模式时： 1. 确认用户拥有的托管目标并部署访问方法（例如 Vercel、Netlify、S3/CloudFront、对象存储 + CDN 或自定义后端 API）。 2. 将 `.openclix/campaigns/openclix-config.json` 上传/部署到该环境。 3. 验证已部署的配置可通过稳定的 HTTPS URL 访问。 4. 将 `OpenClixConfig.endpoint` 设置为已部署的 HTTPS URL。 5. 仅当用户明确请求双路径操作时才保留本地捆绑后备。 6. 接线后运行平台构建/分析检查。关键运行时注意事项： * `OpenClix.initialize(...)` 仅自动获取 HTTP(S) 端点的配置。 * 对于应用内资源 JSON，初始化后始终通过 `OpenClixCampaignManager.replaceConfig(...)` 显式加载和应用配置。 * 对于托管交付，请始终使用 HTTPS 并验证 URL 是否可访问。实施任务完成要求： * 报告选择的交付方式 * 报告源配置路径和应用的运行时配置路径/URL * 对于捆绑模式：区分大小写的文件名和报告的路径奇偶校验结果 * 更新并报告“OpenClixConfig.endpoint”值/位置 * 捆绑模式报告的资源文件路径 * 修改报告的启动/初始化文件路径 * 确认本地资源配置在运行时应用 * 对于托管模式，报告部署的 HTTPS 配置 URL 和上传方法摘要 ## 设计护栏 * 不要发明与提供的分类法相冲突的事件名称。 * 优先选择明确的条件规则（`field: "name"` 和 `field: "property"`）而不是模糊匹配。 * 默认为`连接器：“和”`；仅在有明确理由的情况下使用“或”。 * 当重复类型为“每周”时，包括“weekly_rule.days_of_week”。 * 在引入特定的每个营销活动窗口之前，使用全局安静时间控制。 * 配置生成后，检查现有的 OpenClix 接线，并要求用户选择捆绑交付还是托管交付（如果尚未指定）。 * 在选择资源路径和启动补丁点时重用“openclix-init”发现的项目事实。 * 对于捆绑交付，当代码已经指向具体路径时，永远不要猜测新目录。 * 使用小写的 `openclix-config.json` 除非现有的运行时加载器已经需要另一个精确的文件名。 * 不要依赖“OpenClix.initialize(...)”自动加载的非 HTTP 端点。 * 对于本地 JSON 传递，请始终将 `OpenClixConfig.endpoint` 设置为所选的捆绑路径，并连接显式资源加载 + `OpenClixCampaignManager.replaceConfig(...)`。 * 对于远程 JSON 传输，请将 `OpenClixConfig.endpoint` 设置为 HTTPS URL 并保持有效负载架构与 `openclix/config/v1` 兼容。 * 当询问时，提供特定于环境的上传指导，而不是通用的托管建议。 * 尽量减少集成编辑并与现有项目结构保持一致。 ## 资源 * `references/json-schemas.md`：规划+配置结构和示例。 * `references/openclix-campaign-playbook.md`：触发策略和战役分解。 * `references/schemas/app-profile.schema.json`：应用程序配置文件架构。 * `references/schemas/openclix.schema.json`：此技能使用的规范 OpenClix 模式。

Openclix 设计活动

包含技能