iii-state-reactions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

State Reactions

状态反应

Comparable to: Firebase onSnapshot, Convex mutations

类似技术：Firebase onSnapshot、Convex mutations

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every state reaction needs all of them.

A state trigger fires whenever a value changes within a watched scope

The handler receives

{ new_value, old_value, key, event_type }

describing the change

condition_function_id gates execution — the reaction only fires if the condition returns truthy
Multiple reactions can independently watch the same scope
Reactions fire on
```
state::set
```
,
```
state::update
```
, and
```
state::delete
```
operations

当任务适配时使用以下概念，并非所有状态反应都需要用到全部概念。

state trigger（状态触发器）：当监视作用域内的值发生变更时触发

处理器会接收描述变更的

{ new_value, old_value, key, event_type }

参数

condition_function_id：用于控制执行——仅当条件返回真值时，反应才会触发
多个反应可以独立监视同一作用域
反应会在
```
state::set
```
、
```
state::update
```
和
```
state::delete
```
操作时触发

Architecture

架构

state::set / state::update / state::delete → StateModule emits change event → registerTrigger type:'state' (scope match) → condition_function_id check (if configured) → registerFunction handler ({ new_value, old_value, key, event_type })

state::set / state::update / state::delete → StateModule 发出变更事件 → registerTrigger type:'state'（作用域匹配） → condition_function_id 检查（若已配置） → registerFunction 处理器 ({ new_value, old_value, key, event_type })

iii Primitives Used

iii 使用的原语

Primitive	Purpose
`registerFunction`	Define the reaction handler
`registerTrigger({ type: 'state' })`	Watch a scope for changes
`config: { scope, key, condition_function_id }`	Scope filter and optional condition gate
Event payload: `{ new_value, old_value, key, event_type }`	Change details passed to the handler

原语	用途
`registerFunction`	定义反应处理器
`registerTrigger({ type: 'state' })`	监视作用域内的变更
`config: { scope, key, condition_function_id }`	作用域过滤器和可选的条件控制
事件负载： `{ new_value, old_value, key, event_type }`	传递给处理器的变更详情

Reference Implementation

参考实现

See ../references/state-reactions.js for the full working example — a reaction that watches a state scope and fires side effects when values change, with an optional condition gate.

Also available in Python: ../references/state-reactions.py

Also available in Rust: ../references/state-reactions.rs

完整可运行示例请查看 ../references/state-reactions.js——这是一个监视状态作用域并在值变更时触发副作用的反应，带有可选的条件控制。

同时提供Python版本：../references/state-reactions.py

以及Rust版本：../references/state-reactions.rs

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization
```
registerFunction(id, handler)
```
— define the reaction handler

registerTrigger({ type: 'state', config: { scope, key, condition_function_id } })

— watch for changes

```
payload.new_value
```
/
```
payload.old_value
```
— compare before and after
```
payload.event_type
```
— distinguish between set, update, and delete events

trigger({ function_id: 'state::set', payload })

— write derived state from the reaction

```
const logger = new Logger()
```
— structured logging per reaction

相关代码通常包含以下内容（视情况使用）：

```
registerWorker(url, { workerName })
```
—— 工作进程初始化
```
registerFunction(id, handler)
```
—— 定义反应处理器

registerTrigger({ type: 'state', config: { scope, key, condition_function_id } })

—— 监视变更

```
payload.new_value
```
/
```
payload.old_value
```
—— 比较变更前后的值
```
payload.event_type
```
—— 区分 set、update 和 delete 事件

trigger({ function_id: 'state::set', payload })

—— 通过反应写入派生状态

```
const logger = new Logger()
```
—— 为每个反应添加结构化日志

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Set
```
scope
```
to watch a specific domain (e.g.
```
orders
```
,
```
user-profiles
```
)
Use
```
key
```
to narrow reactions to a single key within a scope
Add a
```
condition_function_id
```
to filter — only react when the condition function returns truthy
Chain reactions by writing state in one handler that triggers another reaction on a different scope

当任务符合以下场景时，可进行相应适配：

设置
```
scope
```
以监视特定领域（例如
```
orders
```
、
```
user-profiles
```
）
使用
```
key
```
将反应范围缩小到作用域内的单个键
添加
```
condition_function_id
```
进行过滤——仅当条件函数返回真值时才触发反应
通过在一个处理器中写入状态，触发另一个作用域上的反应，实现反应链式调用

Engine Configuration

引擎配置

StateModule must be enabled in iii-config.yaml for state triggers to fire. See ../references/iii-config.yaml for the full annotated config reference.

要使状态触发器生效，必须在 iii-config.yaml 中启用 StateModule。完整带注释的配置参考请查看 ../references/iii-config.yaml

Pattern Boundaries

模式边界

If the task is about directly reading or writing state without reactions, prefer
```
iii-state-management
```
.
If the task needs conditional trigger logic shared across trigger types, prefer
```
iii-trigger-conditions
```
.
Stay with
```
iii-state-reactions
```
when the primary need is automatic side effects on state changes.

如果任务仅涉及直接读写状态而无需反应，建议使用
```
iii-state-management
```
。
如果任务需要跨触发器类型共享条件触发逻辑，建议使用
```
iii-trigger-conditions
```
。
当主要需求是在状态变更时自动触发副作用时，应使用
```
iii-state-reactions
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-state-reactions
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

当任务主要涉及 iii 引擎中的
```
iii-state-reactions
```
时，使用此技能。
当请求直接要求实现此模式或等效功能时触发。

Boundaries

边界限制

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将此技能作为无关任务的通用 fallback 方案。
当有更合适的特定 iii 技能时，不得使用此技能。
在应用此技能中的示例前，务必验证环境和安全约束。