长期记忆：pgvector、embedding、chunking、memory_search 工具

const EMBEDDING_URL = 'https://openrouter.ai/api/v1/embeddings'
const EMBEDDING_MODEL = 'openai/text-embedding-3-small' // 固定 1536 维
 
// 这不是模型调用：没有 temperature、不流式、不会「发挥」。
// 同一段文字进去，永远是同一串 1536 个浮点数出来。
export async function embed(texts) {
  const res = await fetch(EMBEDDING_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    // 批量传：一次请求算 N 条，省的是往返延迟不是钱——计费按 token，与批次无关
    body: JSON.stringify({ model: EMBEDDING_MODEL, input: texts }),
  })
  if (!res.ok) throw new Error(`embedding 调用失败：${res.status}`)
  const json = await res.json()
  return json.data.map((item) => item.embedding)
}
 
// 0.02 美元每百万 token；字符数按 1:1 粗估 token（D6 定的保守口径）
export const embeddingCostUsd = (texts) =>
  (texts.reduce((sum, t) => sum + t.length, 0) / 1_000_000) * 0.02

import os
 
import httpx
 
EMBEDDING_URL = "https://openrouter.ai/api/v1/embeddings"
EMBEDDING_MODEL = "openai/text-embedding-3-small"  # 固定 1536 维
 
 
async def embed(texts: list[str]) -> list[list[float]]:
    """不是模型调用：没有 temperature、不流式，同一段文字永远得到同一串向量。"""
    async with httpx.AsyncClient(timeout=30) as client:
        res = await client.post(
            EMBEDDING_URL,
            headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
            # 批量传：省的是往返延迟不是钱——计费按 token，与批次无关
            json={"model": EMBEDDING_MODEL, "input": texts},
        )
    res.raise_for_status()
    return [item["embedding"] for item in res.json()["data"]]
 
 
def embedding_cost_usd(texts: list[str]) -> float:
    # 0.02 美元每百万 token；字符数按 1:1 粗估 token（D6 定的保守口径）
    return sum(len(t) for t in texts) / 1_000_000 * 0.02

// 依赖：java.net.http（JDK 11+）+ Jackson
static final String EMBEDDING_URL = "https://openrouter.ai/api/v1/embeddings";
static final String EMBEDDING_MODEL = "openai/text-embedding-3-small"; // 固定 1536 维
static final ObjectMapper MAPPER = new ObjectMapper();
 
// 不是模型调用：没有 temperature、不流式，同一段文字永远得到同一串向量。
// 向量用 float[] 存：pgvector 的每一维就是 4 字节浮点，用 double[] 白白翻倍内存
static List<float[]> embed(List<String> texts) throws Exception {
    var payload = MAPPER.createObjectNode().put("model", EMBEDDING_MODEL);
    payload.set("input", MAPPER.valueToTree(texts));
    var request = HttpRequest.newBuilder(URI.create(EMBEDDING_URL))
        .header("Authorization", "Bearer " + System.getenv("OPENROUTER_API_KEY"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
        .build();
    var res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() != 200) throw new IOException("embedding 调用失败：" + res.statusCode());
 
    var vectors = new ArrayList<float[]>();
    for (JsonNode item : MAPPER.readTree(res.body()).get("data")) {
        var node = item.get("embedding");
        var vector = new float[node.size()];
        for (int i = 0; i < node.size(); i++) vector[i] = (float) node.get(i).asDouble();
        vectors.add(vector);
    }
    return vectors;
}
 
// 0.02 美元每百万 token；字符数按 1:1 粗估 token（D6 定的保守口径）
static double embeddingCostUsd(List<String> texts) {
    return texts.stream().mapToInt(String::length).sum() / 1_000_000.0 * 0.02;
}

// 请求与响应都声明成 Codable 类型，拼错字段名编译期就报错
struct EmbeddingRequest: Encodable {
    let model = "openai/text-embedding-3-small" // 固定 1536 维
    let input: [String]
}
 
struct EmbeddingResponse: Decodable {
    struct Item: Decodable { let embedding: [Float] }
    let data: [Item]
}
 
/// 不是模型调用：没有 temperature、不流式，同一段文字永远得到同一串向量
func embed(_ texts: [String]) async throws -> [[Float]] {
    let key = ProcessInfo.processInfo.environment["OPENROUTER_API_KEY"] ?? ""
    var request = URLRequest(url: URL(string: "https://openrouter.ai/api/v1/embeddings")!)
    request.httpMethod = "POST"
    request.setValue("Bearer \(key)", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    // 批量传：省的是往返延迟不是钱——计费按 token，与批次无关
    request.httpBody = try JSONEncoder().encode(EmbeddingRequest(input: texts))
 
    let (data, response) = try await URLSession.shared.data(for: request)
    guard (response as? HTTPURLResponse)?.statusCode == 200 else {
        throw URLError(.badServerResponse)
    }
    return try JSONDecoder().decode(EmbeddingResponse.self, from: data).data.map(\.embedding)
}
 
// 0.02 美元每百万 token；字符数按 1:1 粗估 token（D6 定的保守口径）
func embeddingCostUsd(_ texts: [String]) -> Double {
    Double(texts.reduce(0) { $0 + $1.count }) / 1_000_000 * 0.02
}

const CHUNK_SIZE = 400 // 目标 400 字符：一张卡片只装一件事
const OVERLAP = 80 // 重叠 80 字符：句子被切口劈开时，另一块里还留着完整的一份
 
// 从后半段里找最近的自然边界收尾，400 是目标不是硬上限
export function chunkText(text) {
  const chunks = []
  let start = 0
  while (start < text.length) {
    let end = Math.min(start + CHUNK_SIZE, text.length)
    if (end < text.length) {
      const half = start + Math.floor(CHUNK_SIZE / 2)
      const window = text.slice(half, end)
      const hit = Math.max(window.lastIndexOf('。'), window.lastIndexOf('\n'))
      if (hit >= 0) end = half + hit + 1
    }
    const piece = text.slice(start, end).trim()
    if (piece) chunks.push(piece)
    if (end >= text.length) break
    start = Math.max(end - OVERLAP, start + 1) // 回退制造重叠，同时保证一定前进
  }
  return chunks
}

CHUNK_SIZE = 400  # 目标 400 字符：一张卡片只装一件事
OVERLAP = 80  # 重叠 80 字符：句子被切口劈开时，另一块里还留着完整的一份
 
 
def chunk_text(text: str) -> list[str]:
    """从后半段里找最近的自然边界收尾，400 是目标不是硬上限。"""
    chunks: list[str] = []
    start = 0
    while start < len(text):
        end = min(start + CHUNK_SIZE, len(text))
        if end < len(text):
            half = start + CHUNK_SIZE // 2
            window = text[half:end]
            hit = max(window.rfind("。"), window.rfind("\n"))
            if hit >= 0:
                end = half + hit + 1
        piece = text[start:end].strip()
        if piece:
            chunks.append(piece)
        if end >= len(text):
            break
        start = max(end - OVERLAP, start + 1)  # 回退制造重叠，同时保证一定前进
    return chunks

// 依赖：java.util。String.lastIndexOf 就够用，不必为找边界引入正则
static final int CHUNK_SIZE = 400; // 目标 400 字符：一张卡片只装一件事
static final int OVERLAP = 80;     // 重叠 80 字符：句子被劈开时另一块里还留着完整的一份
 
static List<String> chunkText(String text) {
    var chunks = new ArrayList<String>();
    int start = 0;
    while (start < text.length()) {
        int end = Math.min(start + CHUNK_SIZE, text.length());
        if (end < text.length()) {
            int half = start + CHUNK_SIZE / 2;
            String window = text.substring(half, end);
            int hit = Math.max(window.lastIndexOf('。'), window.lastIndexOf('\n'));
            if (hit >= 0) end = half + hit + 1;
        }
        String piece = text.substring(start, end).strip();
        if (!piece.isEmpty()) chunks.add(piece);
        if (end >= text.length()) break;
        start = Math.max(end - OVERLAP, start + 1); // 回退制造重叠，同时保证一定前进
    }
    return List.copyOf(chunks);
}

let chunkSize = 400 // 目标 400 字符：一张卡片只装一件事
let overlap = 80 // 重叠 80 字符：句子被切口劈开时，另一块里还留着完整的一份
 
// Swift 的 String 索引不是整数，先摊成 [Character] 再按下标切：
// 既躲开索引偏移的坑，也保证「一个汉字算一个字符」与另外三份口径一致
func chunkText(_ text: String) -> [String] {
    let chars = Array(text)
    var chunks: [String] = []
    var start = 0
    while start < chars.count {
        var end = min(start + chunkSize, chars.count)
        if end < chars.count {
            let half = start + chunkSize / 2
            if let hit = chars[half..<end].lastIndex(where: { $0 == "。" || $0 == "\n" }) {
                end = hit + 1
            }
        }
        let piece = String(chars[start..<end]).trimmingCharacters(in: .whitespacesAndNewlines)
        if !piece.isEmpty { chunks.append(piece) }
        if end >= chars.count { break }
        start = max(end - overlap, start + 1) // 回退制造重叠，同时保证一定前进
    }
    return chunks
}

// 工具定义照 D5 的规矩写：格式说明 + 合法示例 + 上下界全部进 schema
export const memorySearch = {
  name: 'memory_search',
  description:
    '在这位用户的长期记忆里按语义检索沉淀下来的事实与偏好。' +
    '只查跨会话的长期记忆；本次会话说过的话直接看上文，不要用这个工具。',
  parameters: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: '用一句自然语言描述你想回忆什么，例如 用户的食物忌口',
      },
      limit: {
        type: 'integer',
        description: '返回条数，1 到 10 之间的整数，默认 5',
        minimum: 1,
        maximum: 10,
      },
    },
    required: ['query'],
    // 这里没有 user_id：身份只能来自会话，不能让模型自己填
  },
}
 
const MIN_SCORE = 0.3 // 低于这个宁可不返回；换 embedding 模型要重新标定，见下文
 
export async function runMemorySearch(args, ctx) {
  const errors = validate(memorySearch, args) // D5 那个校验器，一次报全
  if (errors.length > 0) {
    return `调用失败。${errors.join('；')}。请修正后重新调用 memory_search。`
  }
  const vector = await embedOne(args.query)
  // userId 来自会话上下文，不是参数
  const hits = (await ctx.store.search(ctx.userId, vector, args.limit ?? 5)).filter(
    (hit) => hit.score >= MIN_SCORE
  )
  if (hits.length === 0) {
    // 空结果必须说出口：返回空串，模型会当成「没有约束」然后自己编
    return '没有找到相关的长期记忆。请不要凭空推测用户的偏好。'
  }
  return hits
    .map((hit, i) => `${i + 1}. [相似度 ${hit.score.toFixed(2)}｜${hit.createdAt}] ${hit.content}`)
    .join('\n')
}

MEMORY_SEARCH = {
    "name": "memory_search",
    "description": (
        "在这位用户的长期记忆里按语义检索沉淀下来的事实与偏好。"
        "只查跨会话的长期记忆；本次会话说过的话直接看上文，不要用这个工具。"
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "用一句自然语言描述你想回忆什么，例如 用户的食物忌口",
            },
            "limit": {
                "type": "integer",
                "description": "返回条数，1 到 10 之间的整数，默认 5",
                "minimum": 1,
                "maximum": 10,
            },
        },
        "required": ["query"],
        # 这里没有 user_id：身份只能来自会话，不能让模型自己填
    },
}
 
MIN_SCORE = 0.3  # 低于这个宁可不返回；换 embedding 模型要重新标定，见下文
 
 
async def run_memory_search(args: dict, ctx: Context) -> str:
    errors = validate(MEMORY_SEARCH, args)  # D5 那个校验器，一次报全
    if errors:
        return "调用失败。" + "；".join(errors) + "。请修正后重新调用 memory_search。"
 
    vector = await embed_one(args["query"])
    # user_id 来自会话上下文，不是参数
    hits = [
        hit
        for hit in await ctx.store.search(ctx.user_id, vector, args.get("limit", 5))
        if hit.score >= MIN_SCORE
    ]
    if not hits:
        # 空结果必须说出口：返回空串，模型会当成「没有约束」然后自己编
        return "没有找到相关的长期记忆。请不要凭空推测用户的偏好。"
    return "\n".join(
        f"{i}. [相似度 {hit.score:.2f}｜{hit.created_at}] {hit.content}"
        for i, hit in enumerate(hits, start=1)
    )

// 依赖：Jackson。schema 用文本块写，省掉手拼 JSON 的转义
static final double MIN_SCORE = 0.3; // 低于这个相似度宁可不返回；换 embedding 模型要重新标定
 
// readTree 抛受检异常，而静态字段的初始化器没地方声明 throws。schema 是写死的字面量，
// 解析失败只可能是自己把 JSON 敲错了，所以包一层直接快速失败
private static JsonNode schema(String json) {
    try {
        return MAPPER.readTree(json);
    } catch (JsonProcessingException e) {
        throw new IllegalStateException("内置 schema 不是合法 JSON", e);
    }
}
 
// 和 Swift 一样做成工厂方法：D5 的 record ToolSpec 第四个参数 execute 是必填的，
// 而 execute 要用到会话里的 ctx，所以它不能是一个 static final 常量
static ToolSpec memorySearch(AgentContext ctx) {
    return new ToolSpec(
        "memory_search",
        "在这位用户的长期记忆里按语义检索沉淀下来的事实与偏好。"
            + "只查跨会话的长期记忆；本次会话说过的话直接看上文，不要用这个工具。",
        schema("""
        {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "用一句自然语言描述你想回忆什么，例如 用户的食物忌口"
            },
            "limit": {
              "type": "integer",
              "description": "返回条数，1 到 10 之间的整数，默认 5",
              "minimum": 1,
              "maximum": 10
            }
          },
          "required": ["query"]
        }
            """), // 这里没有 user_id：身份只能来自会话，不能让模型自己填
        // ToolImpl.apply 不抛受检异常，所以检索失败要在这里收成一句给模型看的话
        args -> {
            try {
                return runMemorySearch(args, ctx);
            } catch (Exception e) {
                return "长期记忆暂时查不了。请不要凭空推测用户的偏好。";
            }
        });
}
 
// ctx 带着会话里的 userId 和 store，模型碰不到它们
static String runMemorySearch(JsonNode args, AgentContext ctx) throws Exception {
    // 校验拿的是同一份 schema：重新建一次 ToolSpec 只为取它的 parameters，不会执行 execute
    var errors = validate(memorySearch(ctx), args); // D5 那个校验器，一次报全
    if (!errors.isEmpty()) {
        return "调用失败。" + String.join("；", errors) + "。请修正后重新调用 memory_search。";
    }
    var vector = embedOne(args.get("query").asText());
    var hits = ctx.store().search(ctx.userId(), vector, args.path("limit").asInt(5)).stream()
        .filter(hit -> hit.score() >= MIN_SCORE)
        .toList();
    if (hits.isEmpty()) {
        // 空结果必须说出口：返回空串，模型会当成「没有约束」然后自己编
        return "没有找到相关的长期记忆。请不要凭空推测用户的偏好。";
    }
    return IntStream.range(0, hits.size())
        .mapToObj(i -> "%d. [相似度 %.2f｜%s] %s".formatted(
            i + 1, hits.get(i).score(), hits.get(i).createdAt(), hits.get(i).content()))
        .collect(Collectors.joining("\n"));
}

// D5 的 ToolSpec 把「说明书」和「本地实现」绑在同一个类型上，execute 是必填的——
// 所以 Swift 和 Java 这边必须连实现一起交出来，不像 JS 版可以只给一个 schema 对象。
// 这是四门语言里一处真实的差异，不是谁写得更啰嗦
func memorySearchTool(ctx: AgentContext) -> ToolSpec {
    ToolSpec(
        name: "memory_search",
        description: """
            在这位用户的长期记忆里按语义检索沉淀下来的事实与偏好。\
            只查跨会话的长期记忆；本次会话说过的话直接看上文，不要用这个工具。
            """,
        parameters: .init(
            properties: [
                "query": ParameterSpec(
                    type: "string",
                    description: "用一句自然语言描述你想回忆什么，例如 用户的食物忌口"),
                "limit": ParameterSpec(
                    type: "integer",
                    description: "返回条数，1 到 10 之间的整数，默认 5",
                    minimum: 1, maximum: 10),
            ],
            required: ["query"]), // 这里没有 user_id：身份只能来自会话，不能让模型自己填
        // execute 的签名不 throws，所以检索失败要在这里收成一句给模型看的话，
        // 不能让异常穿出去把整轮对话打断
        execute: { args in
            (try? await runMemorySearch(args, ctx: ctx))
                ?? "长期记忆暂时查不了。请不要凭空推测用户的偏好。"
        })
}
 
let minScore: Float = 0.3 // 低于这个宁可不返回；换 embedding 模型要重新标定，见下文
 
func runMemorySearch(_ args: [String: JSONValue], ctx: AgentContext) async throws -> String {
    // 校验拿的是同一份 schema：这里重新建一次 ToolSpec 只是取它的 parameters，不会执行 execute
    if case .failed(let errors) = validate(memorySearchTool(ctx: ctx), args: args) { // D5 那个校验器
        return "调用失败。\(errors.joined(separator: "；"))。请修正后重新调用 memory_search。"
    }
    guard case .string(let query)? = args["query"] else {
        return "调用失败。缺少必填参数 query。请修正后重新调用 memory_search。"
    }
    var limit = 5
    if case .number(let value)? = args["limit"] { limit = Int(value) }
 
    // userID 来自会话上下文，不是参数
    let vector = try await embedOne(query)
    let hits = try await ctx.store.search(userID: ctx.userID, vector: vector, limit: limit)
        .filter { $0.score >= minScore }
    guard !hits.isEmpty else {
        // 空结果必须说出口：返回空串，模型会当成「没有约束」然后自己编
        return "没有找到相关的长期记忆。请不要凭空推测用户的偏好。"
    }
    return hits.enumerated()
        .map { index, hit in
            let score = String(format: "%.2f", hit.score)
            return "\(index + 1). [相似度 \(score)｜\(hit.createdAt)] \(hit.content)"
        }
        .joined(separator: "\n")
}