iii-state-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

State Management

状态管理

Comparable to: Redis, DynamoDB, Memcached

可类比于：Redis、DynamoDB、Memcached

Key Concepts

核心概念

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

State is a scoped key-value store accessed via built-in trigger functions
state::set writes a value; state::get reads it (returns
```
null
```
for missing keys)
state::list retrieves all keys in a scope; state::delete removes a key
state::update performs a partial merge using an
```
ops
```
array for fine-grained changes
Payloads use
```
scope
```
,
```
key
```
, and
```
value
```
to address state entries
State is shared across all functions — use meaningful scope names to avoid collisions

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

状态是通过内置触发函数访问的带作用域的键值存储
state::set 用于写入值；state::get 用于读取值（不存在的键返回
```
null
```
）
state::list 用于检索某个作用域内的所有键；state::delete 用于删除键
state::update 通过
```
ops
```
数组执行部分合并，实现细粒度变更
负载通过
```
scope
```
、
```
key
```
和
```
value
```
定位状态条目
状态在所有函数间共享——使用有意义的作用域名称避免冲突

Architecture

架构

Function → trigger('state::set', { scope, key, value }) → trigger('state::get', { scope, key }) → trigger('state::update', { scope, key, ops }) → trigger('state::delete', { scope, key }) → trigger('state::list', { scope }) → StateModule → KvStore / Redis adapter

iii Primitives Used

iii 所用原语

Primitive	Purpose
`trigger({ function_id: 'state::set', payload })`	Write a value to state
`trigger({ function_id: 'state::get', payload })`	Read a value from state
`trigger({ function_id: 'state::list', payload })`	List all keys in a scope
`trigger({ function_id: 'state::delete', payload })`	Remove a key from state
`trigger({ function_id: 'state::update', payload: { ops } })`	Partial merge with operations array

原语	用途
`trigger({ function_id: 'state::set', payload })`	向状态中写入值
`trigger({ function_id: 'state::get', payload })`	从状态中读取值
`trigger({ function_id: 'state::list', payload })`	列出某个作用域内的所有键
`trigger({ function_id: 'state::delete', payload })`	从状态中删除键
`trigger({ function_id: 'state::update', payload: { ops } })`	通过操作数组执行部分合并

Reference Implementation

参考实现

See ../references/state-management.js for the full working example — functions that read, write, update, and delete state entries across a shared scope.

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

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

完整工作示例请查看 ../references/state-management.js——该示例中的函数可在共享作用域内读写、更新和删除状态条目。

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

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

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization

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

— write state

trigger({ function_id: 'state::get', payload: { scope, key } })

— read state (returns

null

if missing)

trigger({ function_id: 'state::update', payload: { scope, key, ops } })

— partial merge

trigger({ function_id: 'state::list', payload: { scope } })

— enumerate keys

trigger({ function_id: 'state::delete', payload: { scope, key } })

— remove entry

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

使用此模式的代码通常包含以下内容（相关时）：

```
registerWorker(url, { workerName })
```
—— 工作进程初始化

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

—— 写入状态

trigger({ function_id: 'state::get', payload: { scope, key } })

—— 读取状态（不存在时返回

null

）

trigger({ function_id: 'state::update', payload: { scope, key, ops } })

—— 部分合并

trigger({ function_id: 'state::list', payload: { scope } })

—— 枚举键

trigger({ function_id: 'state::delete', payload: { scope, key } })

—— 删除条目

```
const logger = new Logger()
```
—— 结构化日志

Adapting This Pattern

适配此模式

Use the adaptations below when they apply to the task.

Name scopes after your domain (e.g.
```
user-sessions
```
,
```
order-data
```
,
```
config
```
)
Use
```
state::get
```
with a
```
null
```
check to handle missing keys gracefully
Use
```
state::update
```
with
```
ops
```
for partial updates instead of read-modify-write cycles
Combine with
```
iii-queue-processing
```
to persist results after async job completion

当以下适配场景符合任务需求时使用：

根据业务领域命名作用域（例如
```
user-sessions
```
、
```
order-data
```
、
```
config
```
）
使用
```
state::get
```
并配合
```
null
```
检查，优雅处理不存在的键
使用带
```
ops
```
的
```
state::update
```
执行部分更新，替代读取-修改-写入循环
与
```
iii-queue-processing
```
结合，在异步任务完成后持久化结果

Engine Configuration

引擎配置

StateModule must be enabled in iii-config.yaml with a KvStore adapter (file-based or Redis). See ../references/iii-config.yaml for the full annotated config reference.

必须在iii-config.yaml中启用StateModule并配置KvStore适配器（基于文件或Redis）。完整带注释的配置参考请查看 ../references/iii-config.yaml

Pattern Boundaries

模式边界

If the task needs reactive side effects when state changes, prefer
```
iii-state-reactions
```
.
If the task needs real-time client push when data updates, prefer
```
iii-realtime-streams
```
.
Stay with
```
iii-state-management
```
when the primary need is reading and writing persistent key-value data.

如果任务需要在状态变更时触发响应式副作用，优先使用
```
iii-state-reactions
```
。
如果任务需要在数据更新时向客户端实时推送，优先使用
```
iii-realtime-streams
```
。
当主要需求是读写持久化键值数据时，使用
```
iii-state-management
```
。

When to Use

使用场景

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

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

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技能更适合时，不得应用此技能。
在应用此技能中的示例前，务必验证环境和安全约束。