feat(impression): add entity overview state

.gitignore

@@ -60,4 +60,5 @@ build/
 /.codex
 
 # Maven / build outputs
-dependency-reduced-pom.xml
+dependency-reduced-pom.xml
+/.backup/

Partner-Core/src/main/java/work/slhaf/partner/core/action/ActionPoolStateCodec.java

@@ -50,70 +50,70 @@ final class ActionPoolStateCodec {
     }
 
     private static StateValue.Obj encodeExecutableAction(ExecutableAction action) {
-        Map<String, StateValue> actionMap = new LinkedHashMap<>();
-        actionMap.put("kind", StateValue.str(action instanceof SchedulableExecutableAction ? "schedulable" : "immediate"));
-        actionMap.put("uuid", StateValue.str(action.getUuid()));
-        actionMap.put("source", StateValue.str(action.getSource()));
-        actionMap.put("reason", StateValue.str(action.getReason()));
-        actionMap.put("description", StateValue.str(action.getDescription()));
-        actionMap.put("status", StateValue.str(action.getStatus().name()));
-        actionMap.put("tendency", StateValue.str(action.getTendency()));
-        actionMap.put("executing_stage", StateValue.num(action.getExecutingStage()));
+        Map<String, Object> actionMap = new LinkedHashMap<>();
+        actionMap.put("kind", action instanceof SchedulableExecutableAction ? "schedulable" : "immediate");
+        actionMap.put("uuid", action.getUuid());
+        actionMap.put("source", action.getSource());
+        actionMap.put("reason", action.getReason());
+        actionMap.put("description", action.getDescription());
+        actionMap.put("status", action.getStatus().name());
+        actionMap.put("tendency", action.getTendency());
+        actionMap.put("executing_stage", action.getExecutingStage());
 
         String result = resolveExecutableResult(action);
         if (result != null) {
-            actionMap.put("result", StateValue.str(result));
+            actionMap.put("result", result);
         }
         if (action instanceof SchedulableExecutableAction schedulableAction) {
-            actionMap.put("schedule_type", StateValue.str(schedulableAction.getScheduleType().name()));
-            actionMap.put("schedule_content", StateValue.str(schedulableAction.getScheduleContent()));
-            actionMap.put("enabled", StateValue.bool(schedulableAction.getEnabled()));
-            actionMap.put("schedule_histories", StateValue.arr(encodeScheduleHistories(schedulableAction)));
+            actionMap.put("schedule_type", schedulableAction.getScheduleType().name());
+            actionMap.put("schedule_content", schedulableAction.getScheduleContent());
+            actionMap.put("enabled", schedulableAction.getEnabled());
+            actionMap.put("schedule_histories", encodeScheduleHistories(schedulableAction));
         }
 
-        List<StateValue> chainStates = action.getActionChain().entrySet().stream()
+        List<StateValue.Obj> chainStates = action.getActionChain().entrySet().stream()
                 .sorted(Map.Entry.comparingByKey())
-                .<StateValue>map(entry -> {
-                    Map<String, StateValue> stageMap = new LinkedHashMap<>();
-                    stageMap.put("stage", StateValue.num(entry.getKey()));
+                .map(entry -> {
+                    Map<String, Object> stageMap = new LinkedHashMap<>();
+                    stageMap.put("stage", entry.getKey());
                     String stageDescription = action.getStageDescriptions().get(entry.getKey());
                     if (stageDescription != null && !stageDescription.isBlank()) {
-                        stageMap.put("description", StateValue.str(stageDescription));
+                        stageMap.put("description", stageDescription);
                     }
-                    stageMap.put("actions", StateValue.arr(entry.getValue().stream()
-                            .map(metaAction -> (StateValue) encodeMetaAction(metaAction))
-                            .toList()));
+                    stageMap.put("actions", entry.getValue().stream()
+                            .map(ActionPoolStateCodec::encodeMetaAction)
+                            .toList());
                     return StateValue.obj(stageMap);
                 }).toList();
-        actionMap.put("action_chain", StateValue.arr(chainStates));
+        actionMap.put("action_chain", chainStates);
 
-        actionMap.put("history", StateValue.arr(encodeHistoryStages(action.getHistory())));
+        actionMap.put("history", encodeHistoryStages(action.getHistory()));
 
         return StateValue.obj(actionMap);
     }
 
     private static StateValue.Obj encodeMetaAction(MetaAction metaAction) {
-        Map<String, StateValue> metaMap = new LinkedHashMap<>();
-        metaMap.put("name", StateValue.str(metaAction.getName()));
-        metaMap.put("io", StateValue.bool(metaAction.getIo()));
+        Map<String, Object> metaMap = new LinkedHashMap<>();
+        metaMap.put("name", metaAction.getName());
+        metaMap.put("io", metaAction.getIo());
         if (metaAction.getLauncher() != null) {
-            metaMap.put("launcher", StateValue.str(metaAction.getLauncher()));
+            metaMap.put("launcher", metaAction.getLauncher());
         }
-        metaMap.put("type", StateValue.str(metaAction.getType().name()));
-        metaMap.put("location", StateValue.str(metaAction.getLocation()));
-        metaMap.put("params_json", StateValue.str(JSONObject.toJSONString(metaAction.getParams())));
-        metaMap.put("result_status", StateValue.str(metaAction.getResult().getStatus().name()));
+        metaMap.put("type", metaAction.getType().name());
+        metaMap.put("location", metaAction.getLocation());
+        metaMap.put("params_json", JSONObject.toJSONString(metaAction.getParams()));
+        metaMap.put("result_status", metaAction.getResult().getStatus().name());
         if (metaAction.getResult().getData() != null) {
-            metaMap.put("result_data", StateValue.str(metaAction.getResult().getData()));
+            metaMap.put("result_data", metaAction.getResult().getData());
         }
         return StateValue.obj(metaMap);
     }
 
     private static StateValue.Obj encodeHistoryAction(HistoryAction historyAction) {
-        Map<String, StateValue> historyMap = new LinkedHashMap<>();
-        historyMap.put("action_key", StateValue.str(historyAction.actionKey()));
-        historyMap.put("description", StateValue.str(historyAction.description()));
-        historyMap.put("result", StateValue.str(historyAction.result()));
+        Map<String, Object> historyMap = new LinkedHashMap<>();
+        historyMap.put("action_key", historyAction.actionKey());
+        historyMap.put("description", historyAction.description());
+        historyMap.put("result", historyAction.result());
         return StateValue.obj(historyMap);
     }
 
@@ -288,26 +288,26 @@ final class ActionPoolStateCodec {
         return restored;
     }
 
-    private static List<StateValue> encodeHistoryStages(Map<Integer, ? extends List<HistoryAction>> historyMap) {
+    private static List<StateValue.Obj> encodeHistoryStages(Map<Integer, ? extends List<HistoryAction>> historyMap) {
         return historyMap.entrySet().stream()
                 .sorted(Map.Entry.comparingByKey())
-                .<StateValue>map(entry -> {
-                    Map<String, StateValue> stageMap = new LinkedHashMap<>();
-                    stageMap.put("stage", StateValue.num(entry.getKey()));
-                    stageMap.put("actions", StateValue.arr(entry.getValue().stream()
-                            .map(historyAction -> (StateValue) encodeHistoryAction(historyAction))
-                            .toList()));
+                .map(entry -> {
+                    Map<String, Object> stageMap = new LinkedHashMap<>();
+                    stageMap.put("stage", entry.getKey());
+                    stageMap.put("actions", entry.getValue().stream()
+                            .map(ActionPoolStateCodec::encodeHistoryAction)
+                            .toList());
                     return StateValue.obj(stageMap);
                 }).toList();
     }
 
-    private static List<StateValue> encodeScheduleHistories(SchedulableExecutableAction schedulableAction) {
+    private static List<StateValue.Obj> encodeScheduleHistories(SchedulableExecutableAction schedulableAction) {
         return schedulableAction.getScheduleHistories().stream()
-                .<StateValue>map(scheduleHistory -> {
-                    Map<String, StateValue> historyMap = new LinkedHashMap<>();
-                    historyMap.put("end_time", StateValue.str(scheduleHistory.getEndTime().toString()));
-                    historyMap.put("result", StateValue.str(scheduleHistory.getResult()));
-                    historyMap.put("history", StateValue.arr(encodeHistoryStages(scheduleHistory.getHistory())));
+                .map(scheduleHistory -> {
+                    Map<String, Object> historyMap = new LinkedHashMap<>();
+                    historyMap.put("end_time", scheduleHistory.getEndTime().toString());
+                    historyMap.put("result", scheduleHistory.getResult());
+                    historyMap.put("history", encodeHistoryStages(scheduleHistory.getHistory()));
                     return StateValue.obj(historyMap);
                 })
                 .toList();

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/CognitionCapability.java

@@ -1,6 +1,7 @@
 package work.slhaf.partner.core.cognition;
 
 import org.w3c.dom.Element;
+import work.slhaf.partner.core.cognition.context.ContextWorkspace;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.Capability;
 import work.slhaf.partner.framework.agent.model.pojo.Message;
 

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/context/ContextCore.java

@@ -1,4 +1,4 @@
-package work.slhaf.partner.core.cognition;
+package work.slhaf.partner.core.cognition.context;
 
 import com.alibaba.fastjson2.JSONArray;
 import com.alibaba.fastjson2.JSONObject;
@@ -27,7 +27,7 @@ import java.util.concurrent.locks.ReentrantLock;
 
 @Slf4j
 @CapabilityCore(value = "cognition")
-public class CognitionCore implements StateSerializable {
+public class ContextCore implements StateSerializable {
 
     private static final String RECENT_CHAT_MESSAGE_NOTES = """
             消息格式:
@@ -58,7 +58,7 @@ public class CognitionCore implements StateSerializable {
 
     private final ContextWorkspace contextWorkspace = new ContextWorkspace();
 
-    public CognitionCore() {
+    public ContextCore() {
         register();
     }
 
@@ -200,13 +200,12 @@ public class CognitionCore implements StateSerializable {
     public @NotNull State convert() {
         State state = new State();
 
-        List<StateValue.Obj> convertedMessageList = chatMessages.stream().map(message -> {
-            Map<String, StateValue> convertedMap = Map.of(
-                    "role", StateValue.str(message.roleValue()),
-                    "content", StateValue.str(message.getContent())
-            );
-            return StateValue.obj(convertedMap);
-        }).toList();
+        List<StateValue.Obj> convertedMessageList = chatMessages.stream()
+                .map(message -> StateValue.obj(Map.of(
+                        "role", message.roleValue(),
+                        "content", message.getContent()
+                )))
+                .toList();
         state.append("chat_messages", StateValue.arr(convertedMessageList));
 
         return state;

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/context/ContextWorkspace.kt

@@ -1,4 +1,4 @@
-package work.slhaf.partner.core.cognition
+package work.slhaf.partner.core.cognition.context
 
 import com.alibaba.fastjson2.JSONObject
 import org.w3c.dom.Document

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/context/ResolvedContext.kt

@@ -1,4 +1,4 @@
-package work.slhaf.partner.core.cognition
+package work.slhaf.partner.core.cognition.context
 
 import org.w3c.dom.Document
 import work.slhaf.partner.framework.agent.model.pojo.Message

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/impression/ActiveEntity.kt

@@ -0,0 +1,73 @@
+package work.slhaf.partner.core.cognition.impression
+
+import org.w3c.dom.Document
+import org.w3c.dom.Element
+import work.slhaf.partner.core.cognition.context.BlockContent
+import java.util.concurrent.atomic.AtomicReference
+
+class ActiveEntity @JvmOverloads constructor(
+    timestamp: Long = System.currentTimeMillis(),
+    private val _evidences: MutableList<String> = mutableListOf(),
+) : BlockContent("active_entity_$timestamp", "impression") {
+    val evidences: List<String>
+        get() = synchronized(_evidences) { _evidences.toList() }
+
+    private val _subject = AtomicReference("UNKNOWN")
+    val subject: String get() = _subject.get()
+
+    private val _projectedFeatures: MutableMap<String, Double> = mutableMapOf()
+    val projectedFeatures: Map<String, Double>
+        get() = synchronized(_projectedFeatures) { _projectedFeatures.toMap() }
+
+    private val _projectedImpressions: MutableMap<String, Double> = mutableMapOf()
+    val projectedImpressions: Map<String, Double>
+        get() = synchronized(_projectedImpressions) { _projectedImpressions.toMap() }
+
+    fun addEvidence(evidence: String) = synchronized(_evidences) {
+        _evidences.add(evidence)
+    }
+
+    fun updateSubject(subject: String) = _subject.set(subject)
+
+    fun addProjectedFeatures(vararg features: Pair<String, Double>) = synchronized(_projectedFeatures) {
+        features.forEach { _projectedFeatures[it.first] = it.second }
+    }
+
+    fun addProjectedImpressions(vararg impressions: Pair<String, Double>) = synchronized(_projectedImpressions) {
+        impressions.forEach { _projectedImpressions[it.first] = it.second }
+    }
+
+    override fun fillXml(document: Document, root: Element) {
+        appendTextElement(document, root, "subject", subject)
+
+        appendListElement(
+            document,
+            root,
+            "evidences",
+            "evidence",
+            synchronized(_evidences) { _evidences.toList() }
+        )
+
+        appendListElement(
+            document,
+            root,
+            "projected_features",
+            "feature",
+            synchronized(_projectedFeatures) { _projectedFeatures.entries.toList() }
+        ) { entry ->
+            setAttribute("confidence", entry.value.toString())
+            textContent = entry.key
+        }
+
+        appendListElement(
+            document,
+            root,
+            "projected_impressions",
+            "impression",
+            synchronized(_projectedImpressions) { _projectedImpressions.entries.toList() }
+        ) { entry ->
+            setAttribute("confidence", entry.value.toString())
+            textContent = entry.key
+        }
+    }
+}

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/impression/Entity.kt

@@ -0,0 +1,167 @@
+package work.slhaf.partner.core.cognition.impression
+
+import com.alibaba.fastjson2.JSONObject
+import work.slhaf.partner.framework.agent.state.State
+import work.slhaf.partner.framework.agent.state.StateSerializable
+import java.nio.file.Path
+import java.util.*
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.locks.ReentrantLock
+import kotlin.concurrent.withLock
+
+class Entity @JvmOverloads constructor(
+    val uuid: String = UUID.randomUUID().toString(),
+    val subject: String,
+    private val relations: MutableMap<String, MutableMap<String, Double>> = mutableMapOf(),
+    private val impressions: MutableMap<String, IndexableData> = mutableMapOf(),
+    private val features: MutableMap<String, IndexableData> = mutableMapOf()
+) : StateSerializable {
+
+    private val impressionLock = ReentrantLock()
+    private val relationLock = ReentrantLock()
+    private val featureLock = ReentrantLock()
+
+    @JvmOverloads
+    fun updateRelation(
+        target: String,
+        relation: String,
+        strength: Double = 1.0
+    ) = relationLock.withLock {
+        relations.computeIfAbsent(target) { mutableMapOf() }[relation] = strength
+    }
+
+    @JvmOverloads
+    fun updateImpression(
+        impression: String,
+        newImpression: String? = null,
+        confidence: Double = 1.0
+    ): IndexableData = impressionLock.withLock {
+        if (newImpression == null) {
+            impressions.computeIfAbsent(impression) { IndexableData(confidence) }
+                .also {
+                    it.confidence = confidence
+                    if (it.confidence >= 0.9) {
+                        featureLock.withLock { features[impression] = it }
+                    }
+                }
+        } else {
+            impressions.remove(impression)
+            IndexableData(confidence).also {
+                impressions[newImpression] = it
+                if (it.confidence >= 0.9) {
+                    featureLock.withLock { features[newImpression] = it }
+                }
+            }
+        }
+    }
+
+    fun updateFeature(feature: String, newFeature: String? = null, confidence: Double = 1.0) = featureLock.withLock {
+        if (newFeature == null) {
+            features.computeIfAbsent(feature) { IndexableData(confidence) }
+                .also { it.confidence = confidence }
+        } else {
+            features.remove(feature)
+            IndexableData(confidence).also {
+                features[newFeature] = it
+            }
+        }
+    }
+
+    fun removeFeature(feature: String) = featureLock.withLock {
+        features.remove(feature)
+    }
+
+    fun removeImpression(impression: String) = impressionLock.withLock {
+        impressions.remove(impression)
+    }
+
+    @JvmOverloads
+    fun removeRelation(
+        target: String,
+        relation: String? = null
+    ) = relationLock.withLock {
+        if (relation == null) {
+            relations.remove(target)
+        } else {
+            relations[target]?.remove(relation)
+            if (relations[target].isNullOrEmpty()) {
+                relations.remove(target)
+            }
+        }
+    }
+
+    fun showRelations(): Set<RelationView> = relationLock.withLock {
+        relations.map {
+            RelationView(
+                it.key,
+                it.value.toMap()
+            )
+        }.toSet()
+    }
+
+    fun showImpressions(embeddingModel: String): Set<ImpressionView> = impressionLock.withLock {
+        impressions.map {
+            ImpressionView(
+                it.key,
+                it.value.confidence,
+                it.value.getVector(embeddingModel)
+            )
+        }.toSet()
+    }
+
+
+    fun showFeatures(): Set<FeatureView> = featureLock.withLock {
+        features.map {
+            FeatureView(
+                it.key,
+                it.value.confidence
+            )
+        }.toSet()
+    }
+
+    override fun statePath(): Path = Path.of("core", "impression", "entity-$uuid.json")
+
+    override fun load(state: JSONObject) {
+        TODO("Not yet implemented")
+    }
+
+    override fun convert(): State {
+        TODO("Not yet implemented")
+    }
+
+    override fun autoLoadOnRegister(): Boolean = false
+
+    data class IndexableData(
+        var confidence: Double
+    ) {
+        private val vectors: ConcurrentHashMap<String, DoubleArray> = ConcurrentHashMap()
+
+        fun updateVector(
+            embeddingModel: String,
+            vector: DoubleArray
+        ) {
+            vectors[embeddingModel] = vector
+        }
+
+        fun getVector(embeddingModel: String): DoubleArray? {
+            return vectors[embeddingModel]?.copyOf()
+        }
+    }
+
+    data class RelationView(
+        val target: String,
+        val relations: Map<String, Double>
+    )
+
+    data class FeatureView(
+        val feature: String,
+        val confidence: Double
+    )
+
+    @Suppress("ArrayInDataClass")
+    data class ImpressionView(
+        val impression: String,
+        val confidence: Double,
+        val vector: DoubleArray?
+    )
+}

Partner-Core/src/main/java/work/slhaf/partner/core/cognition/impression/ImpressionCore.java

@@ -0,0 +1,88 @@
+package work.slhaf.partner.core.cognition.impression;
+
+import com.alibaba.fastjson2.JSONArray;
+import com.alibaba.fastjson2.JSONObject;
+import org.jetbrains.annotations.NotNull;
+import work.slhaf.partner.framework.agent.factory.capability.annotation.CapabilityCore;
+import work.slhaf.partner.framework.agent.factory.capability.annotation.CapabilityMethod;
+import work.slhaf.partner.framework.agent.state.State;
+import work.slhaf.partner.framework.agent.state.StateSerializable;
+import work.slhaf.partner.framework.agent.state.StateValue;
+
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+@CapabilityCore(value = "cognition")
+public class ImpressionCore implements StateSerializable {
+
+    /**
+     * Keyed by entity uuid. Subject can be revised or merged later, so it should not be used as the stable key.
+     */
+    private final ConcurrentHashMap<String, Entity> knownEntitiesByUuid = new ConcurrentHashMap<>();
+
+    @CapabilityMethod
+    public void updateRelation() {
+    }
+
+    @CapabilityMethod
+    public void updateImpression() {
+    }
+
+    @CapabilityMethod
+    public void showImpressions() {
+    }
+
+    @CapabilityMethod
+    public void projectEntity(Set<ActiveEntity> activeEntities) {
+    }
+
+    @Override
+    public @NotNull Path statePath() {
+        return Path.of("core", "impression.json");
+    }
+
+    @Override
+    public void load(@NotNull JSONObject state) {
+        JSONArray entityArray = state.getJSONArray("entities");
+        if (entityArray == null) {
+            return;
+        }
+
+        knownEntitiesByUuid.clear();
+        for (int i = 0; i < entityArray.size(); i++) {
+            JSONObject entityObject = entityArray.getJSONObject(i);
+            if (entityObject == null) {
+                continue;
+            }
+
+            String uuid = entityObject.getString("uuid");
+            String subject = entityObject.getString("subject");
+            if (uuid == null || uuid.isBlank() || subject == null || subject.isBlank()) {
+                continue;
+            }
+
+            Entity entity = new Entity(uuid, subject);
+            entity.load();
+            knownEntitiesByUuid.put(uuid, entity);
+        }
+    }
+
+
+    @Override
+    public @NotNull State convert() {
+        State state = new State();
+
+        List<StateValue.Obj> entities = knownEntitiesByUuid.values().stream()
+                .map(entity -> StateValue.obj(Map.of(
+                        "uuid", entity.getUuid(),
+                        "subject", entity.getSubject()
+                )))
+                .toList();
+
+        state.append("entities", StateValue.arr(entities));
+        return state;
+    }
+}

Partner-Core/src/main/java/work/slhaf/partner/core/memory/MemoryCore.java

@@ -175,8 +175,7 @@ public class MemoryCore implements StateSerializable {
         State state = new State();
         state.append("memory_session_id", StateValue.str(memorySessionId));
 
-        List<StateValue.Str> unitOverview = memoryUnits.keySet().stream()
-                .map(StateValue::str)
+        List<String> unitOverview = memoryUnits.keySet().stream()
                 .toList();
         state.append("memory_unit_uuid_set", StateValue.arr(unitOverview));
         return state;

Partner-Core/src/main/java/work/slhaf/partner/core/memory/pojo/MemoryUnit.java

@@ -95,25 +95,23 @@ public class MemoryUnit implements StateSerializable {
         state.append("id", StateValue.str(id));
         state.append("update_timestamp", StateValue.num(timestamp));
 
-        List<StateValue.Obj> convertedMessageList = conversationMessages.stream().map(message -> {
-            Map<String, StateValue> convertedMap = Map.of(
-                    "role", StateValue.str(message.roleValue()),
-                    "content", StateValue.str(message.getContent())
-            );
-            return StateValue.obj(convertedMap);
-        }).toList();
+        List<StateValue.Obj> convertedMessageList = conversationMessages.stream()
+                .map(message -> StateValue.obj(Map.of(
+                        "role", message.roleValue(),
+                        "content", message.getContent()
+                )))
+                .toList();
         state.append("conversation_messages", StateValue.arr(convertedMessageList));
 
-        List<StateValue.Obj> convertedSliceList = slices.stream().map(slice -> {
-            Map<String, StateValue> convertedMap = Map.of(
-                    "id", StateValue.str(slice.getId()),
-                    "start_index", StateValue.num(slice.getStartIndex()),
-                    "end_index", StateValue.num(slice.getEndIndex()),
-                    "summary", StateValue.str(slice.getSummary()),
-                    "created_timestamp", StateValue.num(slice.getTimestamp())
-            );
-            return StateValue.obj(convertedMap);
-        }).toList();
+        List<StateValue.Obj> convertedSliceList = slices.stream()
+                .map(slice -> StateValue.obj(Map.of(
+                        "id", slice.getId(),
+                        "start_index", slice.getStartIndex(),
+                        "end_index", slice.getEndIndex(),
+                        "summary", slice.getSummary(),
+                        "created_timestamp", slice.getTimestamp()
+                )))
+                .toList();
         state.append("memory_slices", StateValue.arr(convertedSliceList));
         return state;
     }

Partner-Core/src/main/java/work/slhaf/partner/module/action/builtin/BuiltinCapabilityActionProvider.java

@@ -6,9 +6,9 @@ import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.entity.MetaActionInfo;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.core.memory.MemoryCapability;
 import work.slhaf.partner.core.memory.pojo.MemorySlice;
 import work.slhaf.partner.core.memory.pojo.MemoryUnit;

Partner-Core/src/main/java/work/slhaf/partner/module/action/builtin/BuiltinInterventionActionProvider.java

@@ -12,7 +12,11 @@ import work.slhaf.partner.core.action.entity.MetaAction;
 import work.slhaf.partner.core.action.entity.MetaActionInfo;
 import work.slhaf.partner.core.action.entity.intervention.InterventionType;
 import work.slhaf.partner.core.action.entity.intervention.MetaIntervention;
-import work.slhaf.partner.core.cognition.*;
+import work.slhaf.partner.core.cognition.CognitionCapability;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.CommunicationBlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextWorkspace;
 import work.slhaf.partner.framework.agent.exception.AgentRuntimeException;
 import work.slhaf.partner.framework.agent.exception.ExceptionReporterHandler;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;

Partner-Core/src/main/java/work/slhaf/partner/module/action/executor/ActionCorrectionRecognizer.java

@@ -5,7 +5,7 @@ import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.model.ActivateModel;

Partner-Core/src/main/java/work/slhaf/partner/module/action/executor/ActionCorrector.java

@@ -6,7 +6,7 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.ActionCapability;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.model.ActivateModel;

Partner-Core/src/main/java/work/slhaf/partner/module/action/executor/ExecutingActionBlockManager.java

@@ -6,9 +6,9 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.entity.*;
 import work.slhaf.partner.core.action.entity.intervention.MetaIntervention;
-import work.slhaf.partner.core.cognition.BlockContent;
-import work.slhaf.partner.core.cognition.ContextBlock;
-import work.slhaf.partner.core.cognition.ContextWorkspace;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextWorkspace;
 import work.slhaf.partner.module.StateHintContent;
 import work.slhaf.partner.module.action.executor.entity.HistoryAction;
 

Partner-Core/src/main/java/work/slhaf/partner/module/action/executor/ParamsExtractor.java

@@ -6,7 +6,7 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.entity.MetaActionInfo;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.model.ActivateModel;

Partner-Core/src/main/java/work/slhaf/partner/module/action/planner/ActionPlanner.java

@@ -8,9 +8,9 @@ import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.ActionCapability;
 import work.slhaf.partner.core.action.ActionCore;
 import work.slhaf.partner.core.action.entity.*;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.exception.AgentRuntimeException;
 import work.slhaf.partner.framework.agent.exception.ExceptionReporterHandler;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;

Partner-Core/src/main/java/work/slhaf/partner/module/action/planner/evaluator/ActionEvaluator.java

@@ -6,10 +6,10 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.ActionCapability;
 import work.slhaf.partner.core.action.ActionCore;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
-import work.slhaf.partner.core.cognition.ResolvedContext;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ResolvedContext;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.factory.component.annotation.Init;

Partner-Core/src/main/java/work/slhaf/partner/module/action/planner/extractor/ActionExtractor.java

@@ -2,7 +2,7 @@ package work.slhaf.partner.module.action.planner.extractor;
 
 import org.jetbrains.annotations.NotNull;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.exception.AgentRuntimeException;
 import work.slhaf.partner.framework.agent.exception.ModuleExecutionException;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;

Partner-Core/src/main/java/work/slhaf/partner/module/block.kt

@@ -3,8 +3,8 @@ package work.slhaf.partner.module
 import org.w3c.dom.Document
 import org.w3c.dom.Element
 import work.slhaf.partner.common.base.Block
-import work.slhaf.partner.core.cognition.CommunicationBlockContent
-import work.slhaf.partner.core.cognition.ContextBlock
+import work.slhaf.partner.core.cognition.context.CommunicationBlockContent
+import work.slhaf.partner.core.cognition.context.ContextBlock
 import work.slhaf.partner.framework.agent.model.pojo.Message
 
 abstract class TaskBlock @JvmOverloads constructor(

Partner-Core/src/main/java/work/slhaf/partner/module/communication/CommunicationProducer.java

@@ -5,7 +5,11 @@ import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import org.w3c.dom.Node;
-import work.slhaf.partner.core.cognition.*;
+import work.slhaf.partner.core.cognition.CognitionCapability;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.CommunicationBlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ResolvedContext;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.factory.component.annotation.Init;

Partner-Core/src/main/java/work/slhaf/partner/module/communication/DialogRolling.java

@@ -9,9 +9,9 @@ import work.slhaf.partner.core.action.ActionCapability;
 import work.slhaf.partner.core.action.ActionCore;
 import work.slhaf.partner.core.action.entity.Schedulable;
 import work.slhaf.partner.core.action.entity.StateAction;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.core.memory.MemoryCapability;
 import work.slhaf.partner.core.memory.pojo.MemorySlice;
 import work.slhaf.partner.core.memory.pojo.MemoryUnit;

Partner-Core/src/main/java/work/slhaf/partner/module/memory/runtime/MemoryRuntimeStateCodec.java

@@ -69,8 +69,8 @@ final class MemoryRuntimeStateCodec {
         List<StateValue.Obj> dateIndexStates = dateIndex.entries().entrySet().stream()
                 .sorted(Map.Entry.comparingByKey())
                 .map(entry -> StateValue.obj(Map.of(
-                        "date", StateValue.str(entry.getKey().toString()),
-                        "refs", StateValue.arr(encodeSliceRefs(entry.getValue()))
+                        "date", entry.getKey().toString(),
+                        "refs", encodeSliceRefs(entry.getValue())
                 )))
                 .toList();
         state.append("date_index", StateValue.arr(dateIndexStates));
@@ -82,8 +82,8 @@ final class MemoryRuntimeStateCodec {
                                     TopicMemoryIndex.TopicTreeNode topicNode,
                                     List<StateValue.Obj> topicStates) {
         topicStates.add(StateValue.obj(Map.of(
-                "topic_path", StateValue.str(path),
-                "bindings", StateValue.arr(encodeTopicBindings(topicNode.bindings()))
+                "topic_path", path,
+                "bindings", encodeTopicBindings(topicNode.bindings())
         )));
         for (Map.Entry<String, TopicMemoryIndex.TopicTreeNode> childEntry : topicNode.children().entrySet()) {
             collectTopicStates(path + "->" + childEntry.getKey(), childEntry.getValue(), topicStates);
@@ -93,18 +93,16 @@ final class MemoryRuntimeStateCodec {
     private List<StateValue> encodeTopicBindings(List<TopicMemoryIndex.TopicBinding> bindings) {
         return bindings.stream()
                 .map(binding -> (StateValue) StateValue.obj(Map.of(
-                        "unit_id", StateValue.str(binding.sliceRef().getUnitId()),
-                        "slice_id", StateValue.str(binding.sliceRef().getSliceId()),
-                        "timestamp", StateValue.num(binding.timestamp()),
+                        "unit_id", binding.sliceRef().getUnitId(),
+                        "slice_id", binding.sliceRef().getSliceId(),
+                        "timestamp", binding.timestamp(),
                         "activation_profile", StateValue.obj(Map.of(
-                                "activation_weight", StateValue.num(binding.activationProfile().getActivationWeight()),
-                                "diffusion_weight", StateValue.num(binding.activationProfile().getDiffusionWeight()),
+                                "activation_weight", binding.activationProfile().getActivationWeight(),
+                                "diffusion_weight", binding.activationProfile().getDiffusionWeight(),
                                 "context_independence_weight",
-                                StateValue.num(binding.activationProfile().getContextIndependenceWeight())
+                                binding.activationProfile().getContextIndependenceWeight()
                         )),
-                        "related_topic_paths", StateValue.arr(binding.relatedTopicPaths().stream()
-                                .map(StateValue::str)
-                                .toList())
+                        "related_topic_paths", binding.relatedTopicPaths()
                 )))
                 .toList();
     }
@@ -156,8 +154,8 @@ final class MemoryRuntimeStateCodec {
     private List<StateValue> encodeSliceRefs(List<SliceRef> refs) {
         return refs.stream()
                 .map(ref -> (StateValue) StateValue.obj(Map.of(
-                        "unit_id", StateValue.str(ref.getUnitId()),
-                        "slice_id", StateValue.str(ref.getSliceId())
+                        "unit_id", ref.getUnitId(),
+                        "slice_id", ref.getSliceId()
                 )))
                 .toList();
     }

Partner-Core/src/main/java/work/slhaf/partner/module/memory/selector/MemorySelector.java

@@ -7,9 +7,9 @@ import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.ActionCapability;
 import work.slhaf.partner.core.action.ActionCore;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.factory.component.annotation.InjectModule;

Partner-Core/src/main/java/work/slhaf/partner/module/memory/selector/evaluator/MemoryRecallEvaluator.java

@@ -7,7 +7,7 @@ import org.w3c.dom.Element;
 import work.slhaf.partner.core.action.ActionCapability;
 import work.slhaf.partner.core.action.ActionCore;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.factory.component.annotation.Init;

Partner-Core/src/main/java/work/slhaf/partner/module/memory/selector/extractor/MemoryRecallCueExtractor.java

@@ -5,7 +5,7 @@ import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.framework.agent.factory.component.annotation.InjectModule;

Partner-Core/src/main/java/work/slhaf/partner/module/perceive/PerceiveMonitor.java

@@ -3,10 +3,10 @@ package work.slhaf.partner.module.perceive;
 import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.CommunicationBlockContent;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.CommunicationBlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.core.perceive.PerceiveCapability;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;

Partner-Core/src/main/java/work/slhaf/partner/module/perceive/SystemStatsMonitor.java

@@ -4,9 +4,9 @@ import kotlin.Unit;
 import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.factory.capability.annotation.InjectCapability;
 import work.slhaf.partner.framework.agent.factory.component.abstracts.AbstractAgentModule;
 import work.slhaf.partner.runtime.PartnerRunningFlowContext;

Partner-Core/src/main/java/work/slhaf/partner/runtime/exception/ContextExceptionReporter.java

@@ -3,9 +3,9 @@ package work.slhaf.partner.runtime.exception;
 import org.jetbrains.annotations.NotNull;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
-import work.slhaf.partner.core.cognition.BlockContent;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextBlock;
+import work.slhaf.partner.core.cognition.context.BlockContent;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
 import work.slhaf.partner.framework.agent.exception.AgentException;
 import work.slhaf.partner.framework.agent.exception.ExceptionReport;
 import work.slhaf.partner.framework.agent.exception.ExceptionReporter;

Partner-Core/src/test/java/work/slhaf/partner/core/cognition/CognitionCoreTest.java

@@ -3,6 +3,8 @@ package work.slhaf.partner.core.cognition;
 import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
+import work.slhaf.partner.core.cognition.context.ContextBlock;
+import work.slhaf.partner.core.cognition.context.ContextCore;
 import work.slhaf.partner.framework.agent.model.pojo.Message;
 
 import java.nio.file.Path;
@@ -20,15 +22,15 @@ class CognitionCoreTest {
 
     @Test
     void shouldRenderRecentChatMessagesWithWrapperAndNotes() {
-        CognitionCore cognitionCore = new CognitionCore();
-        cognitionCore.getChatMessages().addAll(List.of(
+        ContextCore contextCore = new ContextCore();
+        contextCore.getChatMessages().addAll(List.of(
                 new Message(Message.Character.USER, "[[USER]: user-1]: hello"),
                 new Message(Message.Character.ASSISTANT, "[NOT_REPLIED]: wait"),
                 new Message(Message.Character.ASSISTANT, "latest message")
         ));
 
-        cognitionCore.refreshRecentChatMessagesContext();
-        String content = cognitionCore.contextWorkspace()
+        contextCore.refreshRecentChatMessagesContext();
+        String content = contextCore.contextWorkspace()
                 .resolve(List.of(ContextBlock.FocusedDomain.COMMUNICATION))
                 .encodeToMessage()
                 .getContent();

Partner-Core/src/test/java/work/slhaf/partner/core/cognition/ContextWorkspaceTest.kt

@@ -2,6 +2,9 @@ package work.slhaf.partner.core.cognition
 
 import org.junit.jupiter.api.Assertions.*
 import org.junit.jupiter.api.Test
+import work.slhaf.partner.core.cognition.context.BlockContent
+import work.slhaf.partner.core.cognition.context.ContextBlock
+import work.slhaf.partner.core.cognition.context.ContextWorkspace
 
 class ContextWorkspaceTest {
 

Partner-Core/src/test/java/work/slhaf/partner/module/action/executor/ActionExecutorTest.java

@@ -10,7 +10,7 @@ import work.slhaf.partner.core.action.ActionCore;
 import work.slhaf.partner.core.action.entity.*;
 import work.slhaf.partner.core.action.runner.RunnerClient;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextWorkspace;
+import work.slhaf.partner.core.cognition.context.ContextWorkspace;
 import work.slhaf.partner.framework.agent.support.Result;
 import work.slhaf.partner.module.action.executor.entity.ExtractorResult;
 import work.slhaf.partner.module.action.executor.entity.HistoryAction;

Partner-Core/src/test/java/work/slhaf/partner/module/communication/CommunicationProducerTest.java

@@ -3,7 +3,7 @@ package work.slhaf.partner.module.communication;
 import org.junit.jupiter.api.Test;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.cognition.CognitionCapability;
-import work.slhaf.partner.core.cognition.ContextWorkspace;
+import work.slhaf.partner.core.cognition.context.ContextWorkspace;
 import work.slhaf.partner.framework.agent.model.pojo.Message;
 import work.slhaf.partner.runtime.PartnerRunningFlowContext;
 

Partner-Core/src/test/java/work/slhaf/partner/module/memory/runtime/MemoryRuntimeTest.java

@@ -8,6 +8,7 @@ import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 import org.w3c.dom.Element;
 import work.slhaf.partner.core.cognition.CognitionCapability;
+import work.slhaf.partner.core.cognition.context.ContextWorkspace;
 import work.slhaf.partner.core.memory.MemoryCapability;
 import work.slhaf.partner.core.memory.pojo.MemorySlice;
 import work.slhaf.partner.core.memory.pojo.MemoryUnit;
@@ -65,8 +66,8 @@ class MemoryRuntimeTest {
             }
 
             @Override
-            public work.slhaf.partner.core.cognition.ContextWorkspace contextWorkspace() {
-                return new work.slhaf.partner.core.cognition.ContextWorkspace();
+            public ContextWorkspace contextWorkspace() {
+                return new ContextWorkspace();
             }
 
             @Override

Partner-Framework/src/main/java/work/slhaf/partner/framework/agent/state/StateCenter.kt

@@ -148,10 +148,130 @@ sealed interface StateValue {
         fun str(value: String) = Str(value)
 
         @JvmStatic
-        fun arr(value: List<StateValue>) = Arr(value)
+        fun arr(value: List<*>): Arr {
+            val visiting = java.util.IdentityHashMap<Any, Unit>()
+            return Arr(convertList(value, visiting))
+        }
 
         @JvmStatic
-        fun obj(value: Map<String, StateValue>) = Obj(value)
+        fun obj(value: Map<String, *>): Obj {
+            val visiting = java.util.IdentityHashMap<Any, Unit>()
+            return Obj(convertMap(value, visiting))
+        }
+
+        private fun convertValue(
+            value: Any?,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): StateValue {
+            return when (value) {
+                null -> error("StateValue does not support null")
+                is StateValue -> normalizeStateValue(value, visiting)
+                is String -> Str(value)
+                is Number -> Num(value)
+                is Boolean -> Bool(value)
+                is List<*> -> Arr(convertList(value, visiting))
+                is Map<*, *> -> Obj(convertGenericMap(value, visiting))
+                else -> error("Unsupported state value type: ${value::class.qualifiedName}")
+            }
+        }
+
+        private fun normalizeStateValue(
+            value: StateValue,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): StateValue {
+            return when (value) {
+                is Num -> value
+                is Bool -> value
+                is Str -> value
+                is Arr -> Arr(convertStateValueList(value.value, visiting))
+                is Obj -> Obj(convertStateValueMap(value.value, visiting))
+            }
+        }
+
+        private fun convertList(
+            value: List<*>,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): List<StateValue> {
+            enterContainer(value, visiting)
+            try {
+                return value.map { convertValue(it, visiting) }
+            } finally {
+                leaveContainer(value, visiting)
+            }
+        }
+
+        private fun convertMap(
+            value: Map<String, *>,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): Map<String, StateValue> {
+            enterContainer(value, visiting)
+            try {
+                return value.entries.associateTo(LinkedHashMap()) { (key, mapValue) ->
+                    key to convertValue(mapValue, visiting)
+                }
+            } finally {
+                leaveContainer(value, visiting)
+            }
+        }
+
+        private fun convertGenericMap(
+            value: Map<*, *>,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): Map<String, StateValue> {
+            enterContainer(value, visiting)
+            try {
+                return value.entries.associateTo(LinkedHashMap()) { (key, mapValue) ->
+                    check(key is String) {
+                        "StateValue object key must be String, but got: ${key?.let { it::class.qualifiedName }}"
+                    }
+                    key to convertValue(mapValue, visiting)
+                }
+            } finally {
+                leaveContainer(value, visiting)
+            }
+        }
+
+        private fun convertStateValueList(
+            value: List<StateValue>,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): List<StateValue> {
+            enterContainer(value, visiting)
+            try {
+                return value.map { normalizeStateValue(it, visiting) }
+            } finally {
+                leaveContainer(value, visiting)
+            }
+        }
+
+        private fun convertStateValueMap(
+            value: Map<String, StateValue>,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ): Map<String, StateValue> {
+            enterContainer(value, visiting)
+            try {
+                return value.entries.associateTo(LinkedHashMap()) { (key, mapValue) ->
+                    key to normalizeStateValue(mapValue, visiting)
+                }
+            } finally {
+                leaveContainer(value, visiting)
+            }
+        }
+
+        private fun enterContainer(
+            container: Any,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ) {
+            check(visiting.put(container, Unit) == null) {
+                "Circular reference detected while constructing StateValue"
+            }
+        }
+
+        private fun leaveContainer(
+            container: Any,
+            visiting: java.util.IdentityHashMap<Any, Unit>
+        ) {
+            visiting.remove(container)
+        }
     }
 }
 

Partner-Framework/src/test/java/work/slhaf/partner/framework/agent/state/StateTest.kt

@@ -0,0 +1,60 @@
+package work.slhaf.partner.framework.agent.state
+
+fun main() {
+    testNormalStateJson()
+    println()
+    testCircularReference()
+}
+
+private fun testNormalStateJson() {
+    val nestedMap = linkedMapOf(
+        "name" to "partner",
+        "enabled" to true,
+        "count" to 3,
+        "tags" to listOf("agent", "runtime", "state-center"),
+        "meta" to linkedMapOf(
+            "version" to "0.1.0",
+            "experimental" to false
+        )
+    )
+
+    val state = State()
+    state.append("root", StateValue.obj(nestedMap))
+    state.append(
+        "arr",
+        StateValue.arr(
+            listOf(
+                "hello",
+                123,
+                true,
+                linkedMapOf(
+                    "nested" to "value"
+                )
+            )
+        )
+    )
+
+    println("=== normal state ===")
+    println(state.toString())
+}
+
+private fun testCircularReference() {
+    val cyclicMap = linkedMapOf<String, Any>()
+    cyclicMap["name"] = "cyclic"
+    cyclicMap["self"] = cyclicMap
+
+    println("=== circular reference ===")
+
+    try {
+        val state = State()
+        state.append("cyclic", StateValue.obj(cyclicMap))
+
+        // 如果前面没有抛错，这里再触发最终 JSON 输出
+        println(state.toString())
+        error("Expected circular reference detection, but no exception was thrown.")
+    } catch (e: IllegalStateException) {
+        println("circular reference detected as expected:")
+        println(e.message)
+    }
+}
+

PartnerCtl/pom.xml

@@ -123,6 +123,7 @@
                         <buildArg>-H:+ReportExceptionStackTraces</buildArg>
                         <buildArg>--initialize-at-build-time=kotlin.DeprecationLevel</buildArg>
                         <buildArg>-H:IncludeResourceBundles=i18n.messages</buildArg>
+                        <buildArg>-H:IncludeLocales=zh-CN</buildArg>
                     </buildArgs>
                 </configuration>
             </plugin>

README.md

@@ -25,12 +25,54 @@ Partner 分为 `Partner-Framework` 与 `Partner-Core` 两层。前者提供配
 
 ## 项目启动
 
-**环境要求**
+### 环境要求
+
+**基础运行要求**
 
 - JDK 21
-- Maven 3.x
 
-### 手动准备环境并启动
+**仅在从源码构建 Partner Runtime 或外部模块时需要**
+
+- Maven 3.x
+- Git
+
+### 推荐方式：PartnerCtl
+
+`PartnerCtl` 用于完成 Partner 的首次初始化、运行时安装与启动管理。相比手动准备运行目录和配置文件，使用它可以更快完成最小可运行环境的搭建。
+
+#### 初始化
+
+```bash
+partnerctl init
+```
+
+初始化流程会引导完成：
+
+- 选择 `PARTNER_HOME`
+- 安装 Partner Runtime
+  - 从源码构建
+  - 下载发布版 jar
+- 配置 Gateway
+- 配置模型 Provider
+- 可选立即启动 Partner
+
+#### 启动
+
+如果初始化完成后未选择立即启动，可执行：
+
+```bash
+partnerctl run
+```
+
+如需后台运行：
+
+```bash
+partnerctl run -d
+```
+
+PartnerCtl 默认读取 `PARTNER_HOME` 指定的运行目录；若未设置，则使用 `~/.partner`。
+
+### 手动方式：从源码构建并启动
 
 #### 克隆项目并构建
 
@@ -162,4 +204,3 @@ Partner/
 ## License
 
 暂未指定。
-