类class io.agentscope.core.state 2.x

JsonFileAgentStateStore

public class JsonFileAgentStateStore implements AgentStateStore

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:69–417

把 AgentState 按用户与会话写入本地 JSON 文件，适合单机开发与调试。位于 io.agentscope.core.state 包，实现 AgentStateStore。核心成员包括 save、get、getList、exists、delete、listSessionIds。

JSON file-based AgentStateStore implementation.

On-disk layout:


&lt;root&gt;/
__anon__/ ← anonymous (userId == null) sessions
&lt;safe(sessionId)&gt;/
agent_state.json
memory_messages.jsonl
memory_messages.hash
&lt;safe(userId)&gt;/ ← per-user sessions
&lt;safe(sessionId)&gt;/
agent_state.json
...

safe(...) keeps the literal string when it matches ^[a-zA-Z0-9_\-.]+$; otherwise it is Base64-URL encoded (no padding) so the filesystem accepts it.

Features: atomic file operations, UTF-8 encoding, graceful handling of missing sessions, hash-based append-or-rewrite for list state.

构造器摘要Constructor Summary

构造器Constructor	说明Description
`public` `JsonFileAgentStateStore()`	在指定目录创建 JSON 文件状态存储。 Create a `JsonFileAgentStateStore` with the default root: `~/.agentscope/state`.
`public` `JsonFileAgentStateStore(Path rootDirectory)`	在指定目录创建 JSON 文件状态存储。 Create a `JsonFileAgentStateStore` rooted at the given directory.

方法摘要Method Summary

方法Method	说明Description
`public void save(String userId, String sessionId, String key,` `State value)`	保存一个或一组状态对象。 Performs the save operation.
`public void save(String userId, String sessionId, String key, List<? extends` `State> values)`	保存一个或一组状态对象。 Performs the save operation.
`public T extends` `State Optional<T> get(String userId, String sessionId, String key, Class<T> type)`	读取指定类型的单个状态。 Performs the get operation.
`public T extends` `State List<T> getList(String userId, String sessionId, String key, Class<T> itemType)`	获取列表。 Returns the list.
`public boolean exists(String userId, String sessionId)`	判断会话状态是否存在。 Performs the exists operation.
`public void delete(String userId, String sessionId)`	删除会话或其中的某个状态键。 Performs the delete operation.
`public void delete(String userId, String sessionId, String key)`	删除会话或其中的某个状态键。 Performs the delete operation.
`public Set<String> listSessionIds(String userId)`	列出用户的全部会话 ID。 Lists the session ids.
`public Path getRootDirectory()`	获取根目录。 Returns the configured root directory (for diagnostics).
`public Mono<Integer> clearAllSessions()`	清空所有会话。 Clear every session under every user.
`protected Path getSessionDir(String userId, String sessionId)`	获取会话目录。 Returns the directory under which all state files for `(userId, sessionId)` live.

构造器详情Constructor Detail

JsonFileAgentStateStore

public JsonFileAgentStateStore()

创建JsonFileAgentStateStore使用默认根:~/.agentscope/state。

Create a JsonFileAgentStateStore with the default root: ~/.agentscope/state.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:83–85

JsonFileAgentStateStore

public JsonFileAgentStateStore(Path rootDirectory)

初始化 JsonFileAgentStateStore 实例。

Create a JsonFileAgentStateStore rooted at the given directory.

参数Parameters

名称Name	类型Type	说明Description
`rootDirectory`	Path	根目录（类型 `Path`）。root directory under which user / session sub-directories live

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:92–99

方法详情Method Detail

save

public void save(String userId, String sessionId, String key, State value)

保存数据到持久化存储。

Performs the save operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`value`	State	值（类型 `State`）。The value.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:101–111

save

public void save(String userId, String sessionId, String key, List<? extends State> values)

保存数据到持久化存储。

Performs the save operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`values`	List<? extends State>	值（类型 `List`）。The values.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:113–136

get

public T extends State Optional<T> get(String userId, String sessionId, String key, Class<T> type)

按条件读取数据。

Performs the get operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`type`	Class<T>	类型（类型 `Class`）。The type.

返回Returns Optional<T>

返回可选。Returns optional.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:165–178

getList

public T extends State List<T> getList(String userId, String sessionId, String key, Class<T> itemType)

获取列表。

Returns the list.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.
`itemType`	Class<T>	条目类型（类型 `Class`）。The item type.

返回Returns List<T>

返回列出。Returns list.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:180–201

exists

public boolean exists(String userId, String sessionId)

判断数据是否存在。

Performs the exists operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:203–206

delete

public void delete(String userId, String sessionId)

删除数据。

Performs the delete operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:208–214

delete

public void delete(String userId, String sessionId, String key)

删除数据。

Performs the delete operation.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.
`key`	String	键（类型 `String`）。The key.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:216–223

listSessionIds

public Set<String> listSessionIds(String userId)

列出 listSessionIds。

Lists the session ids.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.

返回Returns Set<String>

返回设置。Returns set.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:225–240

getRootDirectory

public Path getRootDirectory()

获取根目录。

Returns the configured root directory (for diagnostics).

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:243–245

clearAllSessions

public Mono<Integer> clearAllSessions()

清空所有会话。

Clear every session under every user.

返回Returns Mono<Integer>

返回Mono。Returns mono.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:250–279

getSessionDir

protected Path getSessionDir(String userId, String sessionId)

获取会话目录。

Returns the directory under which all state files for (userId, sessionId) live.

参数Parameters

名称Name	类型Type	说明Description
`userId`	String	用户标识（类型 `String`）。The user id.
`sessionId`	String	会话标识（类型 `String`）。The session id.

返回Returns Path

返回路径。Returns path.

源码Source io/agentscope/core/state/JsonFileAgentStateStore.java:285–289

继承成员Inherited Members

继承自Members inherited from AgentStateStore

supportsVersioning, getVersioned, saveIfVersion, close, UNVERSIONED