From 25940cd21b827b7c312dd43cb250d5c449d203d7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 24 Jan 2026 11:31:33 +0000 Subject: [PATCH 1/3] Initial plan From 7a4a8456a4c46016c3fbdd094a5f77214809dbe9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 24 Jan 2026 11:36:43 +0000 Subject: [PATCH 2/3] Clarify Plugin Lifecycle terminology to avoid confusion with Triggers Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- HOOK_TRIGGER_CLARIFICATION.md | 69 +++++++++++++++++++++++++ packages/spec/src/system/plugin.test.ts | 20 +++---- packages/spec/src/system/plugin.zod.ts | 12 ++--- 3 files changed, 85 insertions(+), 16 deletions(-) create mode 100644 HOOK_TRIGGER_CLARIFICATION.md diff --git a/HOOK_TRIGGER_CLARIFICATION.md b/HOOK_TRIGGER_CLARIFICATION.md new file mode 100644 index 000000000..d1d7589fb --- /dev/null +++ b/HOOK_TRIGGER_CLARIFICATION.md @@ -0,0 +1,69 @@ +# Hook vs Trigger Clarification + +## 问题 (Question) +审核所有的zod，我们之前有定义一个类似现在trigger的hook规范，现在还需要保留吗？ + +## 分析结果 (Analysis Results) + +### 现有的 "Hook-like" 规范 (Current "Hook-like" Specifications) + +经过全面审查，发现以下几个与"hook"或"trigger"相关的规范： + +1. **Trigger** (`src/data/trigger.zod.ts`) - 数据库级别的业务逻辑钩子 + - 目的：在数据库操作前后执行业务逻辑 + - 时机：before/after insert/update/delete + - 功能：数据验证、设置默认值、更新关联记录、阻止操作 + +2. **Plugin Lifecycle** (`src/system/plugin.zod.ts`) - 插件生命周期回调 + - 目的：插件安装和生命周期管理 + - 回调：onInstall, onEnable, onDisable, onUninstall, onUpgrade + - 功能：插件初始化、服务启停、数据迁移、资源清理 + +3. **Webhook** (`src/system/webhook.zod.ts`) - 外部HTTP集成 + - 目的：与外部系统的HTTP回调集成 + - 类型：create, update, delete, undelete, api + - 方向：出站(push)和入站(receive) + +4. **Workflow** (`src/data/workflow.zod.ts`) - 业务流程自动化 + - 目的：业务流程自动化规则 + - 触发器：on_create, on_update, on_create_or_update, on_delete, schedule + - 动作：field_update, email_alert, sms_notification等 + +### 发现的问题 (Issues Found) + +1. **术语混淆**：Plugin Lifecycle 在描述中使用了 "Hook" 术语，但其实是生命周期回调，与 Trigger 的语义不同 +2. **未实现的计划**：开发路线图中提到的 `hooks.zod.ts`（包含 beforeObjectCreate, afterRecordSave 等）实际上与现有的 Trigger 重复 + +### 建议 (Recommendations) + +**✅ 推荐方案：保留现有结构，澄清术语** + +1. **Trigger** - 保留，作为数据库级别的业务逻辑钩子（这是正确的设计） +2. **Plugin Lifecycle** - 保留，但将术语从 "Hook" 改为 "Lifecycle callback"，避免混淆 +3. **不需要新的 hooks.zod.ts** - Trigger 已经覆盖了计划中的扩展点 + +### 已实施的更改 (Changes Made) + +1. 更新了 `src/system/plugin.zod.ts` 中的描述，将 "Hook called on..." 改为 "Lifecycle callback on..." +2. 将类型名称从 `PluginLifecycleHooks` 改为 `PluginLifecycleCallbacks`，更准确地反映其用途 +3. 更新了相关测试文件 + +### 语义区别 (Semantic Differences) + +| 方面 | Trigger | Plugin Lifecycle | Webhook | Workflow | +|------|---------|------------------|---------|----------| +| **层级** | 数据/记录 | 系统/插件 | 集成 | 流程 | +| **同步** | 是 | 是 | 可异步 | 可异步 | +| **可修改数据** | 是(before) | 通过QL API | 否 | 是 | +| **可阻止操作** | 是(before) | 否 | 否 | 通过条件 | +| **执行上下文** | 每条记录 | 每个插件 | 每个事件 | 每条规则 | + +## 结论 (Conclusion) + +**不需要保留旧的 hook 规范，因为：** +1. 代码库中不存在单独的旧 `hook.zod.ts` 文件 +2. 当前的 Trigger 规范已经非常完善，涵盖了数据库级别的钩子需求 +3. Plugin Lifecycle 服务于不同的目的（插件生命周期管理），已通过术语澄清与 Trigger 区分开来 +4. 计划中的 Hook Registry Protocol 会与 Trigger 重复，不需要实现 + +**Trigger 规范应该作为 ObjectStack 的主要 "hook" 机制保留和使用。** diff --git a/packages/spec/src/system/plugin.test.ts b/packages/spec/src/system/plugin.test.ts index 821108fd7..1ac0a8357 100644 --- a/packages/spec/src/system/plugin.test.ts +++ b/packages/spec/src/system/plugin.test.ts @@ -1,10 +1,10 @@ import { describe, it, expect } from 'vitest'; -import { - PluginContextSchema, +import { + PluginContextSchema, PluginLifecycleSchema, PluginSchema, type PluginContextData, - type PluginLifecycleHooks, + type PluginLifecycleCallbacks, type PluginDefinition, } from './plugin.zod'; @@ -139,13 +139,13 @@ describe('PluginContextSchema', () => { describe('PluginLifecycleSchema', () => { it('should accept empty lifecycle (all hooks optional)', () => { - const lifecycle: PluginLifecycleHooks = {}; + const lifecycle: PluginLifecycleCallbacks = {}; expect(() => PluginLifecycleSchema.parse(lifecycle)).not.toThrow(); }); it('should accept lifecycle with onInstall hook', () => { - const lifecycle: PluginLifecycleHooks = { + const lifecycle: PluginLifecycleCallbacks = { onInstall: async (context: PluginContextData) => { // Installation logic }, @@ -155,7 +155,7 @@ describe('PluginLifecycleSchema', () => { }); it('should accept lifecycle with onEnable hook', () => { - const lifecycle: PluginLifecycleHooks = { + const lifecycle: PluginLifecycleCallbacks = { onEnable: async (context: PluginContextData) => { // Enable logic }, @@ -165,7 +165,7 @@ describe('PluginLifecycleSchema', () => { }); it('should accept lifecycle with onDisable hook', () => { - const lifecycle: PluginLifecycleHooks = { + const lifecycle: PluginLifecycleCallbacks = { onDisable: async (context: PluginContextData) => { // Disable logic }, @@ -175,7 +175,7 @@ describe('PluginLifecycleSchema', () => { }); it('should accept lifecycle with onUninstall hook', () => { - const lifecycle: PluginLifecycleHooks = { + const lifecycle: PluginLifecycleCallbacks = { onUninstall: async (context: PluginContextData) => { // Uninstall logic }, @@ -185,7 +185,7 @@ describe('PluginLifecycleSchema', () => { }); it('should accept lifecycle with onUpgrade hook', () => { - const lifecycle: PluginLifecycleHooks = { + const lifecycle: PluginLifecycleCallbacks = { onUpgrade: async (context: PluginContextData, fromVersion: string, toVersion: string) => { // Upgrade logic }, @@ -195,7 +195,7 @@ describe('PluginLifecycleSchema', () => { }); it('should accept lifecycle with all hooks', () => { - const lifecycle: PluginLifecycleHooks = { + const lifecycle: PluginLifecycleCallbacks = { onInstall: async (context: PluginContextData) => { await context.ql.object('plugin_data').syncSchema(); }, diff --git a/packages/spec/src/system/plugin.zod.ts b/packages/spec/src/system/plugin.zod.ts index bdf21a5d1..549215624 100644 --- a/packages/spec/src/system/plugin.zod.ts +++ b/packages/spec/src/system/plugin.zod.ts @@ -172,7 +172,7 @@ export const PluginLifecycleSchema = z.object({ .args(PluginContextSchema) .returns(z.promise(z.void())) .optional() - .describe('Hook called on plugin installation'), + .describe('Lifecycle callback on plugin installation'), /** * Called when the plugin is enabled. @@ -184,7 +184,7 @@ export const PluginLifecycleSchema = z.object({ .args(PluginContextSchema) .returns(z.promise(z.void())) .optional() - .describe('Hook called when plugin is enabled'), + .describe('Lifecycle callback when plugin is enabled'), /** * Called when the plugin is disabled. @@ -196,7 +196,7 @@ export const PluginLifecycleSchema = z.object({ .args(PluginContextSchema) .returns(z.promise(z.void())) .optional() - .describe('Hook called when plugin is disabled'), + .describe('Lifecycle callback when plugin is disabled'), /** * Called when the plugin is uninstalled. @@ -208,7 +208,7 @@ export const PluginLifecycleSchema = z.object({ .args(PluginContextSchema) .returns(z.promise(z.void())) .optional() - .describe('Hook called on plugin uninstallation'), + .describe('Lifecycle callback on plugin uninstallation'), /** * Called when the plugin is upgraded to a new version. @@ -222,7 +222,7 @@ export const PluginLifecycleSchema = z.object({ .args(PluginContextSchema, z.string(), z.string()) .returns(z.promise(z.void())) .optional() - .describe('Hook called on plugin upgrade'), + .describe('Lifecycle callback on plugin upgrade'), }); /** @@ -248,5 +248,5 @@ export const PluginSchema = PluginLifecycleSchema.extend({ * TypeScript types */ export type PluginContextData = z.infer; -export type PluginLifecycleHooks = z.infer; +export type PluginLifecycleCallbacks = z.infer; export type PluginDefinition = z.infer; From 0989ab9c24bffd1de1425dd4a051d658179bd779 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <50353452+hotlong@users.noreply.github.com> Date: Sat, 24 Jan 2026 19:53:38 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E5=88=A0=E9=99=A4=20HOOK=5FTRIGGER=5FCLARI?= =?UTF-8?q?FICATION.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HOOK_TRIGGER_CLARIFICATION.md | 69 ----------------------------------- 1 file changed, 69 deletions(-) delete mode 100644 HOOK_TRIGGER_CLARIFICATION.md diff --git a/HOOK_TRIGGER_CLARIFICATION.md b/HOOK_TRIGGER_CLARIFICATION.md deleted file mode 100644 index d1d7589fb..000000000 --- a/HOOK_TRIGGER_CLARIFICATION.md +++ /dev/null @@ -1,69 +0,0 @@ -# Hook vs Trigger Clarification - -## 问题 (Question) -审核所有的zod，我们之前有定义一个类似现在trigger的hook规范，现在还需要保留吗？ - -## 分析结果 (Analysis Results) - -### 现有的 "Hook-like" 规范 (Current "Hook-like" Specifications) - -经过全面审查，发现以下几个与"hook"或"trigger"相关的规范： - -1. **Trigger** (`src/data/trigger.zod.ts`) - 数据库级别的业务逻辑钩子 - - 目的：在数据库操作前后执行业务逻辑 - - 时机：before/after insert/update/delete - - 功能：数据验证、设置默认值、更新关联记录、阻止操作 - -2. **Plugin Lifecycle** (`src/system/plugin.zod.ts`) - 插件生命周期回调 - - 目的：插件安装和生命周期管理 - - 回调：onInstall, onEnable, onDisable, onUninstall, onUpgrade - - 功能：插件初始化、服务启停、数据迁移、资源清理 - -3. **Webhook** (`src/system/webhook.zod.ts`) - 外部HTTP集成 - - 目的：与外部系统的HTTP回调集成 - - 类型：create, update, delete, undelete, api - - 方向：出站(push)和入站(receive) - -4. **Workflow** (`src/data/workflow.zod.ts`) - 业务流程自动化 - - 目的：业务流程自动化规则 - - 触发器：on_create, on_update, on_create_or_update, on_delete, schedule - - 动作：field_update, email_alert, sms_notification等 - -### 发现的问题 (Issues Found) - -1. **术语混淆**：Plugin Lifecycle 在描述中使用了 "Hook" 术语，但其实是生命周期回调，与 Trigger 的语义不同 -2. **未实现的计划**：开发路线图中提到的 `hooks.zod.ts`（包含 beforeObjectCreate, afterRecordSave 等）实际上与现有的 Trigger 重复 - -### 建议 (Recommendations) - -**✅ 推荐方案：保留现有结构，澄清术语** - -1. **Trigger** - 保留，作为数据库级别的业务逻辑钩子（这是正确的设计） -2. **Plugin Lifecycle** - 保留，但将术语从 "Hook" 改为 "Lifecycle callback"，避免混淆 -3. **不需要新的 hooks.zod.ts** - Trigger 已经覆盖了计划中的扩展点 - -### 已实施的更改 (Changes Made) - -1. 更新了 `src/system/plugin.zod.ts` 中的描述，将 "Hook called on..." 改为 "Lifecycle callback on..." -2. 将类型名称从 `PluginLifecycleHooks` 改为 `PluginLifecycleCallbacks`，更准确地反映其用途 -3. 更新了相关测试文件 - -### 语义区别 (Semantic Differences) - -| 方面 | Trigger | Plugin Lifecycle | Webhook | Workflow | -|------|---------|------------------|---------|----------| -| **层级** | 数据/记录 | 系统/插件 | 集成 | 流程 | -| **同步** | 是 | 是 | 可异步 | 可异步 | -| **可修改数据** | 是(before) | 通过QL API | 否 | 是 | -| **可阻止操作** | 是(before) | 否 | 否 | 通过条件 | -| **执行上下文** | 每条记录 | 每个插件 | 每个事件 | 每条规则 | - -## 结论 (Conclusion) - -**不需要保留旧的 hook 规范，因为：** -1. 代码库中不存在单独的旧 `hook.zod.ts` 文件 -2. 当前的 Trigger 规范已经非常完善，涵盖了数据库级别的钩子需求 -3. Plugin Lifecycle 服务于不同的目的（插件生命周期管理），已通过术语澄清与 Trigger 区分开来 -4. 计划中的 Hook Registry Protocol 会与 Trigger 重复，不需要实现 - -**Trigger 规范应该作为 ObjectStack 的主要 "hook" 机制保留和使用。**