程序包 io.agentscope.core.state

类 JsonFileAgentStateStore

java.lang.Object
io.agentscope.core.state.JsonFileAgentStateStore
所有已实现的接口:
AgentStateStore
public class JsonFileAgentStateStore extends Object implements AgentStateStore
JSON file-based AgentStateStore implementation.

On-disk layout: 

 <root>/
   __anon__/                       ← anonymous (userId == null) sessions
     <safe(sessionId)>/
       agent_state.json
       memory_messages.jsonl
       memory_messages.hash
   <safe(userId)>/                ← per-user sessions
     <safe(sessionId)>/
       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.

  • 构造器详细资料

    • JsonFileAgentStateStore

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

    • JsonFileAgentStateStore

      public JsonFileAgentStateStore(Path rootDirectory)
      Create a JsonFileAgentStateStore rooted at the given directory.
      参数:
      rootDirectory - root directory under which user / session sub-directories live

  • 方法详细资料

    • save

      public void save(String userId, String sessionId, String key, State value)
      从接口复制的说明: AgentStateStore
      Save a single state value (full replacement).

      This method saves a single state object, replacing any existing value with the same key.

      指定者:
      save 在接口中 AgentStateStore
      参数:
      userId - nullable user identifier; null = anonymous
      sessionId - session identifier; must be non-null and non-blank
      key - the state key (e.g., "agent_state", "toolkit_activeGroups")
      value - the state value to save

    • save

      public void save(String userId, String sessionId, String key, List<? extends State> values)
      从接口复制的说明: AgentStateStore
      Save a list of state values.

      Different implementations may use different storage strategies:

      Callers should always pass the full list. The implementation decides the storage strategy.

      指定者:
      save 在接口中 AgentStateStore
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key (e.g., "memory_messages")
      values - the full list of state values

    • get

      public <T extends State> Optional<T> get(String userId, String sessionId, String key, Class<T> type)
      从接口复制的说明: AgentStateStore
      Get a single state value.
      指定者:
      get 在接口中 AgentStateStore
      类型参数:
      T - the state type
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key
      type - the expected state type
      返回:
      the state value, or empty if not found

    • getList

      public <T extends State> List<T> getList(String userId, String sessionId, String key, Class<T> itemType)
      从接口复制的说明: AgentStateStore
      Get a list of state values.
      指定者:
      getList 在接口中 AgentStateStore
      类型参数:
      T - the item type
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key
      itemType - the expected item type
      返回:
      the list of state values, or empty list if not found

    • exists

      public boolean exists(String userId, String sessionId)
      从接口复制的说明: AgentStateStore
      Check if a session exists.
      指定者:
      exists 在接口中 AgentStateStore
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      返回:
      true if the session has any persisted state

    • delete

      public void delete(String userId, String sessionId)
      从接口复制的说明: AgentStateStore
      Delete a session and all its data.
      指定者:
      delete 在接口中 AgentStateStore
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank

    • delete

      public void delete(String userId, String sessionId, String key)
      从接口复制的说明: AgentStateStore
      Delete a single state entry within a session.
      指定者:
      delete 在接口中 AgentStateStore
      参数:
      userId - nullable user identifier
      sessionId - session identifier; must be non-null and non-blank
      key - the state key to delete

    • listSessionIds

      public Set<String> listSessionIds(String userId)
      从接口复制的说明: AgentStateStore
      List session identifiers visible under the given user namespace.

      Use userId == null to list anonymous sessions. Pass a concrete user to list only that user's sessions. There is no API to list across users in one call — that is a separate administrative concern (admin starter handles it by iterating known users).

      指定者:
      listSessionIds 在接口中 AgentStateStore
      参数:
      userId - nullable user identifier
      返回:
      set of session identifiers stored under userId

    • getRootDirectory

      public Path getRootDirectory()
      Returns the configured root directory (for diagnostics).

    • clearAllSessions

      public reactor.core.publisher.Mono<Integer> clearAllSessions()
      Clear every session under every user. Returns the number of session directories removed.

    • getSessionDir

      protected Path getSessionDir(String userId, String sessionId)
      Returns the directory under which all state files for (userId, sessionId) live. Subclasses can override this if they need a different layout.