union-ark-web 1.0.1

package/ark-control/src/main/java/com/union/control/service/impl/AgentProxyServiceImpl.java

@@ -0,0 +1,143 @@
+package com.union.control.service.impl;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.union.control.service.AgentProxyService;
+import com.union.control.service.AgentResponse;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.client.ClientHttpResponse;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.ResponseErrorHandler;
+import org.springframework.web.client.RestTemplate;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.nio.charset.StandardCharsets;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+@Service("agentProxyService")
+public class AgentProxyServiceImpl implements AgentProxyService {
+    private static final Logger logger = LoggerFactory.getLogger(AgentProxyServiceImpl.class);
+    private final String pyAppBaseUrl;
+    private final RestTemplate http;
+    private final ObjectMapper json;
+
+    @Autowired
+    public AgentProxyServiceImpl(
+            @Value("${agent.py-app-base-url}") String pyAppBaseUrl,
+            ObjectMapper json,
+            @Value("${AGENT_MAX_RUN_SECONDS:900}") double maxRunSeconds) {
+        this(pyAppBaseUrl, new RestTemplate(), json);
+        double millis = Math.ceil(maxRunSeconds * 1000);
+        if (!Double.isFinite(millis) || millis < 1 || millis > Integer.MAX_VALUE)
+            throw new IllegalArgumentException("AGENT_MAX_RUN_SECONDS is out of range");
+        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
+        factory.setConnectTimeout((int) millis);
+        factory.setReadTimeout((int) millis);
+        http.setRequestFactory(factory);
+    }
+
+    public AgentProxyServiceImpl(String pyAppBaseUrl, RestTemplate http, ObjectMapper json) {
+        this.pyAppBaseUrl = pyAppBaseUrl.replaceAll("/+$", "");
+        this.http = http;
+        this.json = json;
+        ResponseErrorHandler passThroughErrors = new ResponseErrorHandler() {
+            @Override
+            public boolean hasError(ClientHttpResponse response) {
+                return false;
+            }
+
+            @Override
+            public void handleError(ClientHttpResponse response) {}
+        };
+        this.http.setErrorHandler(passThroughErrors);
+    }
+
+    public AgentResponse sync(String cookie, String payload) {
+        long startedAt = System.nanoTime();
+        logger.info("Agent call started mode=sync payload_chars={}", payload.length());
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        headers.set(HttpHeaders.COOKIE, cookie);
+        try {
+            ResponseEntity<byte[]> response = http.exchange(
+                    pyAppBaseUrl + "/agent/v1/runs/sync",
+                    HttpMethod.POST,
+                    new HttpEntity<>(payload.getBytes(StandardCharsets.UTF_8), headers),
+                    byte[].class
+            );
+            logCompleted("sync", response.getStatusCode().value(), startedAt);
+            return result(response);
+        } catch (RuntimeException error) {
+            logFailed("sync", startedAt, error);
+            throw error;
+        }
+    }
+
+    public AgentResponse scheduled(String authorization) {
+        long startedAt = System.nanoTime();
+        logger.info("Agent call started mode=scheduled");
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        headers.set(HttpHeaders.AUTHORIZATION, authorization);
+        try {
+            ResponseEntity<byte[]> response = http.exchange(
+                    pyAppBaseUrl + "/agent/v1/runs/scheduled",
+                    HttpMethod.POST,
+                    new HttpEntity<byte[]>(new byte[]{'{', '}'}, headers),
+                    byte[].class);
+            logCompleted("scheduled", response.getStatusCode().value(), startedAt);
+            return result(response);
+        } catch (RuntimeException error) {
+            logFailed("scheduled", startedAt, error);
+            throw error;
+        }
+    }
+
+    public AgentResponse cancel(String cookie, String conversationId, String runId) {
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        headers.set(HttpHeaders.COOKIE, cookie);
+        Map<String, Object> body = new LinkedHashMap<>();
+        body.put("conversationId", conversationId);
+        body.put("runId", runId);
+        return result(http.exchange(
+                pyAppBaseUrl + "/agent/v1/runs/cancel",
+                HttpMethod.POST,
+                new HttpEntity<Map<String, Object>>(body, headers),
+                byte[].class
+        ));
+    }
+
+    private AgentResponse result(ResponseEntity<byte[]> response) {
+        try {
+            String body = json.writeValueAsString(json.readTree(
+                    new String(response.getBody(), StandardCharsets.UTF_8)));
+            return new AgentResponse(response.getStatusCode().value(), body);
+        } catch (Exception error) {
+            throw new IllegalStateException("Agent 返回的不是合法 JSON", error);
+        }
+    }
+
+    private static void logCompleted(String mode, int status, long startedAt) {
+        long duration = (System.nanoTime() - startedAt) / 1_000_000L;
+        if (status >= 400)
+            logger.warn("Agent call completed mode={} status={} duration_ms={}", mode, status, duration);
+        else
+            logger.info("Agent call completed mode={} status={} duration_ms={}", mode, status, duration);
+    }
+
+    private static void logFailed(String mode, long startedAt, RuntimeException error) {
+        logger.warn("Agent call failed mode={} duration_ms={} error_type={}", mode,
+                (System.nanoTime() - startedAt) / 1_000_000L, error.getClass().getSimpleName());
+    }
+
+}

package/ark-control/src/main/java/com/union/control/service/impl/ConversationServiceImpl.java

@@ -0,0 +1,245 @@
+package com.union.control.service.impl;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.union.control.mapper.AgentExecutionMapper;
+import com.union.control.mapper.ConversationMapper;
+import com.union.control.mapper.ScheduledTaskMapper;
+import com.union.control.service.ConversationService;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.NoSuchElementException;
+import java.util.UUID;
+
+import static com.union.control.utils.AgentSupport.*;
+
+@Service("conversationService")
+public class ConversationServiceImpl implements ConversationService {
+    private final ConversationMapper conversationMapper;
+    private final AgentExecutionMapper executionMapper;
+    private final ScheduledTaskMapper scheduledTaskMapper;
+    private final ObjectMapper json;
+
+    public ConversationServiceImpl(
+            ConversationMapper conversationMapper,
+            AgentExecutionMapper executionMapper,
+            ScheduledTaskMapper scheduledTaskMapper,
+            ObjectMapper json) {
+        this.conversationMapper = conversationMapper;
+        this.executionMapper = executionMapper;
+        this.scheduledTaskMapper = scheduledTaskMapper;
+        this.json = json;
+    }
+
+    public Map<String, Object> userInfo(String input) {
+        Map<String, Object> request = request(json, input);
+        Map<String, Object> user = new LinkedHashMap<>();
+        user.put("userId", userId(request));
+        user.put("orgCode", identity(request, "orgCode"));
+        return ok(user);
+    }
+
+    public Map<String, Object> conversations(String input) {
+        Map<String, Object> request = request(json, input);
+        String userId = userId(request);
+        int limit = integer(request, "limit", 1, 100);
+        requireRange(limit, 1, 100, "limit");
+        return ok(conversationMapper.findConversations(userId, limit));
+    }
+
+    public Map<String, Object> conversation(String input) {
+        Map<String, Object> request = request(json, input);
+        String userId = userId(request);
+        String conversationId = text(request, "conversationId", 64, true);
+        requireId(conversationId);
+        Map<String, Object> result = loadConversation(userId, conversationId);
+        List<Map<String, Object>> executions = executionMapper.findExecutions(userId, conversationId);
+        result.put("messages", loadBrowserMessages(userId, conversationId, executions));
+        result.put("executions", publicExecutions(executions));
+        return ok(result);
+    }
+
+    public Map<String, Object> conversationMessages(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String conversationId = text(payload, "conversationId", 64, true);
+        requireId(conversationId);
+        requireOwned(userId, conversationId, false);
+        Map<String, Object> response = new LinkedHashMap<>();
+        response.put("success", true);
+        response.put("messages", loadRootMessages(userId, conversationId));
+        return response;
+    }
+
+    public Map<String, Object> rename(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String conversationId = text(payload, "conversationId", 64, true);
+        String title = text(payload, "title", 255, true);
+        requireId(conversationId);
+        if (conversationMapper.updateConversationTitle(title, conversationId, userId) != 1)
+            throw new NoSuchElementException("会话不存在");
+        return ok(loadConversation(userId, conversationId));
+    }
+
+    @Transactional
+    public Map<String, Object> deleteConversation(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String conversationId = text(payload, "conversationId", 64, true);
+        requireId(conversationId);
+        requireOwned(userId, conversationId, true);
+        conversationMapper.softDeleteMessages(conversationId, userId);
+        executionMapper.softDeleteExecutions(conversationId, userId);
+        scheduledTaskMapper.softDeleteByConversation(conversationId, userId);
+        int updated = conversationMapper.softDeleteConversation(conversationId, userId);
+        if (updated != 1) throw new NoSuchElementException("会话不存在");
+        return ok(null);
+    }
+
+    /** Materializes a trusted completed result through the normal conversation path. */
+    @Transactional
+    String materializeCompletedConversation(
+            String userId, String title, String prompt, String content, String agentName) {
+        String random = UUID.randomUUID().toString().replace("-", "");
+        String conversationId = "scheduled-" + random;
+        String runId = "scheduled-open-" + random;
+        conversationMapper.insertConversation(conversationId, userId, title);
+        Map<String, Object> execution = new LinkedHashMap<>();
+        execution.put("runId", runId);
+        execution.put("conversationId", conversationId);
+        execution.put("userId", userId);
+        execution.put("agentName", agentName);
+        executionMapper.insertCompletedRootExecution(execution);
+        insertTrustedMessage(conversationId, userId,
+                "scheduled-user-" + random, number(execution.get("id")), "user", 1, prompt);
+        insertTrustedMessage(conversationId, userId,
+                "scheduled-assistant-" + random, number(execution.get("id")), "assistant", 2, content);
+        return conversationId;
+    }
+
+    private void insertTrustedMessage(
+            String conversationId, String userId, String messageId, long executionId,
+            String role, long sequence, String content) {
+        Map<String, Object> payload = new LinkedHashMap<>();
+        payload.put("content", content);
+        try {
+            conversationMapper.insertMessage(conversationId, userId, messageId, executionId,
+                    role, sequence, json.writeValueAsString(payload));
+        } catch (Exception error) {
+            throw new IllegalArgumentException("可信消息无法持久化", error);
+        }
+    }
+
+
+    private List<Object> loadRootMessages(String userId, String conversationId) {
+        List<Map<String, Object>> rows = conversationMapper.findRootMessages(userId, conversationId);
+        List<Object> messages = new ArrayList<>();
+        for (Map<String, Object> row : rows) {
+            messages.add(message(row));
+        }
+        return messages;
+    }
+
+    private List<Object> loadBrowserMessages(
+            String userId, String conversationId, List<Map<String, Object>> executions) {
+        Map<String, Map<String, Object>> byRun = new LinkedHashMap<>();
+        for (Map<String, Object> execution : executions)
+            byRun.put(String.valueOf(execution.get("runId")), execution);
+        List<Map<String, Object>> rows = conversationMapper.findBrowserMessages(userId, conversationId);
+        List<Object> result = new ArrayList<>();
+        Map<String, List<Object>> childMessages = new LinkedHashMap<>();
+        for (Map<String, Object> row : rows) {
+            if (row.get("parentExecutionId") == null) {
+                result.add(message(row));
+                continue;
+            }
+            String runId = String.valueOf(row.get("runId"));
+            List<Object> messages = childMessages.get(runId);
+            if (messages == null) {
+                messages = new ArrayList<>();
+                childMessages.put(runId, messages);
+                result.add(activity(byRun.get(runId), messages));
+            }
+            messages.add(message(row));
+        }
+        for (Map<String, Object> execution : executions) {
+            if (execution.get("parentExecutionId") == null) continue;
+            String runId = String.valueOf(execution.get("runId"));
+            if (!childMessages.containsKey(runId))
+                result.add(activity(execution, new ArrayList<>()));
+        }
+        return result;
+    }
+
+    private Map<String, Object> message(Map<String, Object> row) {
+        try {
+            Object parsed = json.readValue(String.valueOf(row.get("payload")),
+                    new TypeReference<Object>() {});
+            if (!(parsed instanceof Map)) throw new IllegalStateException("消息数据损坏");
+            Map<String, Object> message = new LinkedHashMap<>();
+            message.put("id", row.get("messageId"));
+            message.put("role", row.get("role"));
+            @SuppressWarnings("unchecked") Map<String, Object> payload =
+                    (Map<String, Object>) parsed;
+            message.putAll(payload);
+            return message;
+        } catch (IllegalStateException error) {
+            throw error;
+        } catch (Exception error) {
+            throw new IllegalStateException("消息数据损坏", error);
+        }
+    }
+
+    private static Map<String, Object> activity(
+            Map<String, Object> execution, List<Object> messages) {
+        if (execution == null) throw new IllegalStateException("execution 数据损坏");
+        Map<String, Object> content = new LinkedHashMap<>();
+        content.put("runId", execution.get("runId"));
+        content.put("parentRunId", execution.get("parentRunId"));
+        content.put("agentName", execution.get("agentName"));
+        content.put("delegationToolCallId", execution.get("delegationToolCallId"));
+        content.put("task", execution.get("task"));
+        content.put("status", execution.get("status"));
+        content.put("messages", messages);
+        content.put("errorCode", execution.get("errorCode"));
+        Map<String, Object> activity = new LinkedHashMap<>();
+        activity.put("id", "subagent:" + execution.get("runId"));
+        activity.put("role", "activity");
+        activity.put("activityType", "subagent_execution");
+        activity.put("content", content);
+        return activity;
+    }
+
+    private Map<String, Object> loadConversation(String userId, String conversationId) {
+        Map<String, Object> conversation =
+                conversationMapper.findConversation(userId, conversationId);
+        if (conversation == null) throw new NoSuchElementException("会话不存在");
+        return conversation;
+    }
+
+    private static List<Map<String, Object>> publicExecutions(List<Map<String, Object>> rows) {
+        List<Map<String, Object>> result = new ArrayList<>();
+        for (Map<String, Object> row : rows) result.add(publicExecution(row));
+        return result;
+    }
+
+    private static Map<String, Object> publicExecution(Map<String, Object> row) {
+        Map<String, Object> result = new LinkedHashMap<>(row);
+        result.remove("id");
+        result.remove("parentExecutionId");
+        return result;
+    }
+
+
+    private void requireOwned(String userId, String conversationId, boolean lock) {
+        if (conversationMapper.requireOwned(conversationId, userId, lock) == null) {
+            throw new NoSuchElementException("会话不存在");
+        }
+    }
+}

package/ark-control/src/main/java/com/union/control/service/impl/MemoryStoreServiceImpl.java

@@ -0,0 +1,252 @@
+package com.union.control.service.impl;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.union.control.mapper.MemoryStoreMapper;
+import com.union.control.service.MemoryStoreService;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Pattern;
+
+import static com.union.control.utils.AgentSupport.*;
+
+@Service("memoryStoreService")
+public class MemoryStoreServiceImpl implements MemoryStoreService {
+    private static final Pattern MEMORY_PATH =
+            Pattern.compile("[A-Za-z0-9._:@+-]+(?:/[A-Za-z0-9._:@+-]+)*");
+
+    private final MemoryStoreMapper mapper;
+    private final ObjectMapper json;
+
+    public MemoryStoreServiceImpl(MemoryStoreMapper mapper, ObjectMapper json) {
+        this.mapper = mapper;
+        this.json = json;
+    }
+
+    public Map<String, Object> memoryRead(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String path = memoryPath(userId, payload, "path");
+        int maxChars = integer(payload, "maxChars", 1, 65536);
+        List<Map<String, Object>> rows = mapper.readMemory(userId, path);
+        Map<String, Object> response = success();
+        if (rows.isEmpty()) {
+            response.put("file", null);
+            return response;
+        }
+        Map<String, Object> row = rows.get(0);
+        String content = String.valueOf(row.get("content"));
+        Map<String, Object> file = new LinkedHashMap<>();
+        file.put("content", content.substring(0, Math.min(content.length(), maxChars)));
+        file.put("version", String.valueOf(row.get("version")));
+        file.put("operationId", row.get("operationId"));
+        file.put("truncated", content.length() > maxChars);
+        response.put("file", file);
+        return response;
+    }
+
+    public Map<String, Object> memoryList(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String prefix = memoryPrefix(userId, payload);
+        int limit = integer(payload, "limit", 1, 1000);
+        List<String> paths = mapper.listMemoryPaths(userId, likePrefix(prefix), limit);
+        Map<String, Object> response = success();
+        response.put("paths", paths);
+        return response;
+    }
+
+    public Map<String, Object> memoryOperation(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String operationId = text(payload, "operationId", 128, true);
+        String fingerprint = text(payload, "fingerprint", 128, true);
+        List<Map<String, Object>> rows = mapper.findMemoryOperation(userId, operationId, false);
+        if (rows.isEmpty()) {
+            Map<String, Object> response = success();
+            response.put("mutation", null);
+            return response;
+        }
+        return replayResponse(rows.get(0), fingerprint);
+    }
+
+    @Transactional
+    public Map<String, Object> memoryWrite(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String path = memoryPath(userId, payload, "path");
+        String content = text(payload, "content", 65536, true);
+        String expected = optionalText(payload, "expectedVersion", 32);
+        Operation operation = operation(payload);
+        Map<String, Object> replay = replay(userId, operation);
+        if (replay != null) return replay;
+        List<Map<String, Object>> rows = memoryRow(userId, path);
+        String currentVersion = rows.isEmpty() ? null : String.valueOf(rows.get(0).get("version"));
+        if (!same(currentVersion, expected))
+            return memoryError("version_conflict", "memory version 已变化");
+        boolean existed = !rows.isEmpty();
+        Long prior = mapper.currentMemoryVersion(userId, path);
+        long version = (prior == null ? 0 : prior) + 1;
+        if (existed) {
+            mapper.updateMemoryFile(content, version, operation == null ? null : operation.id,
+                    rows.get(0).get("id"));
+        } else {
+            mapper.insertMemoryFile(userId, path, content, version,
+                    operation == null ? null : operation.id);
+        }
+        saveReceipt(userId, operation, version, existed);
+        Map<String, Object> response = success();
+        response.put("mutation", mutation(version, false, existed));
+        return response;
+    }
+
+    @Transactional
+    public Map<String, Object> memoryDelete(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String path = memoryPath(userId, payload, "path");
+        String expected = optionalText(payload, "expectedVersion", 32);
+        Operation operation = operation(payload);
+        Map<String, Object> replay = replay(userId, operation);
+        if (replay != null) return replay;
+        List<Map<String, Object>> rows = memoryRow(userId, path);
+        String currentVersion = rows.isEmpty() ? null : String.valueOf(rows.get(0).get("version"));
+        if (!same(currentVersion, expected))
+            return memoryError("version_conflict", "memory version 已变化");
+        boolean existed = !rows.isEmpty();
+        if (existed) {
+            mapper.softDeleteMemoryFile(rows.get(0).get("id"));
+        }
+        saveReceipt(userId, operation, null, existed);
+        Map<String, Object> response = success();
+        response.put("mutation", mutation(null, false, existed));
+        return response;
+    }
+
+    public Map<String, Object> memorySearch(String input) {
+        Map<String, Object> payload = request(json, input);
+        String userId = userId(payload);
+        String prefix = memoryPrefix(userId, payload);
+        String query = text(payload, "query", 512, true);
+        int limit = integer(payload, "limit", 1, 100);
+        int maxFiles = integer(payload, "maxFiles", 1, 1000);
+        int maxChars = integer(payload, "maxChars", 1, 100000);
+        int maxFileChars = integer(payload, "maxFileChars", 1, 65536);
+        List<Map<String, Object>> rows = mapper.searchMemory(
+                userId, likePrefix(prefix), maxFiles + 1);
+        boolean truncated = rows.size() > maxFiles;
+        List<Map<String, Object>> matches = new ArrayList<>();
+        int remaining = maxChars;
+        int scanned = Math.min(rows.size(), maxFiles);
+        String lowerQuery = query.toLowerCase();
+        for (int index = 0; index < scanned && matches.size() < limit && remaining > 0; index++) {
+            Map<String, Object> row = rows.get(index);
+            String path = String.valueOf(row.get("path"));
+            String content = String.valueOf(row.get("content"));
+            String bounded = content.substring(0, Math.min(content.length(), maxFileChars));
+            if (!path.toLowerCase().contains(lowerQuery) && !bounded.toLowerCase().contains(lowerQuery))
+                continue;
+            String snippet = bounded.substring(0, Math.min(bounded.length(), remaining));
+            Map<String, Object> match = new LinkedHashMap<>();
+            match.put("path", path);
+            match.put("snippet", snippet);
+            match.put("score", 1.0d);
+            matches.add(match);
+            remaining -= path.length() + snippet.length();
+            if (content.length() > maxFileChars) truncated = true;
+        }
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("matches", matches);
+        result.put("scanned", scanned);
+        result.put("truncated", truncated);
+        Map<String, Object> response = success();
+        response.put("result", result);
+        return response;
+    }
+
+    private List<Map<String, Object>> memoryRow(String userId, String path) {
+        return mapper.findMemoryRow(userId, path);
+    }
+
+    private Map<String, Object> replay(String userId, Operation operation) {
+        if (operation == null) return null;
+        List<Map<String, Object>> rows = mapper.findMemoryOperation(userId, operation.id, true);
+        if (rows.isEmpty()) return null;
+        return replayResponse(rows.get(0), operation.fingerprint);
+    }
+
+    private Map<String, Object> replayResponse(
+            Map<String, Object> row, String fingerprint) {
+        if (!fingerprint.equals(String.valueOf(row.get("fingerprint"))))
+            return memoryError("operation_conflict", "operation id 已被不同参数使用");
+        Map<String, Object> response = success();
+        response.put("mutation", mutation(row.get("resultVersion"), true,
+                number(row.get("existed")) != 0));
+        return response;
+    }
+
+    private void saveReceipt(String userId, Operation operation, Long version, boolean existed) {
+        if (operation == null) return;
+        mapper.insertMemoryOperation(userId, operation.id, operation.fingerprint, version,
+                existed ? 1 : 0);
+    }
+
+    private Operation operation(Map<String, Object> payload) {
+        Object raw = payload.get("operation");
+        if (raw == null) return null;
+        if (!(raw instanceof Map)) throw new IllegalArgumentException("operation 非法");
+        @SuppressWarnings("unchecked")
+        Map<String, Object> value = (Map<String, Object>) raw;
+        return new Operation(text(value, "id", 128, true),
+                text(value, "fingerprint", 128, true));
+    }
+
+    private String memoryPath(String userId, Map<String, Object> payload, String key) {
+        String path = text(payload, key, 512, true);
+        if (!MEMORY_PATH.matcher(path).matches() || path.contains("..") ||
+                !path.startsWith(userId + "/personal/"))
+            throw new IllegalArgumentException("memory path 非法");
+        return path;
+    }
+
+    private String memoryPrefix(String userId, Map<String, Object> payload) {
+        String prefix = optionalText(payload, "prefix", 512);
+        if (prefix == null) prefix = "";
+        if (prefix.isEmpty()) prefix = userId + "/personal/";
+        if (!prefix.startsWith(userId + "/personal/") || prefix.contains(".."))
+            throw new IllegalArgumentException("memory prefix 非法");
+        return prefix;
+    }
+
+
+    private static Map<String, Object> mutation(
+            Object version, boolean replayed, boolean existed) {
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("version", version == null ? null : String.valueOf(version));
+        result.put("replayed", replayed);
+        result.put("existed", existed);
+        return result;
+    }
+
+    private static Map<String, Object> memoryError(String code, String message) {
+        Map<String, Object> response = new LinkedHashMap<>();
+        response.put("success", false);
+        response.put("errorCode", code);
+        response.put("errorMsg", message);
+        return response;
+    }
+
+    private static final class Operation {
+        private final String id;
+        private final String fingerprint;
+
+        private Operation(String id, String fingerprint) {
+            this.id = id;
+            this.fingerprint = fingerprint;
+        }
+    }
+}