Skip to content
Python
8.5 KB
Raw Blame
import type { CoreContextQuery, ReadOutcome } from "./core-client.js";
import { PRODUCT } from "./version.js";

export const CONTEXT_QUERY_MAX_CHARACTERS = 2_000;
const CONTEXT_KINDS = ["raw", "memory"] as const;
export interface ContextSearchInput {
  query: string;
  kinds: Array<(typeof CONTEXT_KINDS)[number]>;
  raw_source_ids?: string[];
  limit: number;
  character_budget: number;
  timeout_ms: number;
  /** Whose memories to search. Omitted for the default user (`local`). */
  user_id?: string;
}

/** The CLI's JSON document mirrors Core's SDK-native context schema v2. */
export interface ContextSearchDocument {
  schema_version: 2;
  product: string;
  state:
    | "grounded"
    | "empty"
    | "partial"
    | "unavailable"
    | "denied"
    | "not_found"
    | "rejected"
    | "invalid";
  code?: string;
  request_id?: string;
  items: Array<Record<string, unknown>>;
  used_characters?: number;
  truncated?: boolean;
  total_ms?: number;
}

export async function searchContext(
  query: CoreContextQuery,
  input: ContextSearchInput,
): Promise<ContextSearchDocument> {
  const outcome = await query<unknown>(input);
  if (outcome.state !== "ok") return failed(outcome);
  const validated = validateContextResponse(outcome.data, input);
  return (
    validated ?? {
      schema_version: 2,
      product: PRODUCT,
      state: "invalid",
      code: "response_invalid",
      items: [],
    }
  );
}

export function parseContextText(
  bytes: Buffer,
  maxCharacters = CONTEXT_QUERY_MAX_CHARACTERS,
): string | null {
  if (bytes.byteLength > maxCharacters * 4 + 2) return null;
  const text = new TextDecoder("utf-8", { fatal: true });
  let decoded: string;
  try {
    decoded = text.decode(bytes);
  } catch {
    return null;
  }
  const value = decoded.replace(/\r?\n$/, "");
  if (
    value.length < 1 ||
    value.length > maxCharacters ||
    [...value].some((character) => {
      const code = character.charCodeAt(0);
      return code <= 31 || code === 127;
    })
  ) {
    return null;
  }
  return value;
}

export async function readBoundedStdin(): Promise<Buffer | null> {
  const chunks: Buffer[] = [];
  let total = 0;
  const maximum = CONTEXT_QUERY_MAX_CHARACTERS * 4 + 2;
  for await (const value of process.stdin) {
    const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
    total += chunk.byteLength;
    if (total > maximum) return null;
    chunks.push(chunk);
  }
  return Buffer.concat(chunks, total);
}

export function contextExitCode(document: ContextSearchDocument): number {
  return ["grounded", "empty", "partial"].includes(document.state) ? 0 : 1;
}

export function renderContextText(document: ContextSearchDocument): string {
  if (document.state === "unavailable") {
    // No lexical fallback: without the embedding service nothing is searched.
    return document.code === "embedding_unavailable"
      ? "向量服务不可用,无法检索;请检查向量模型配置。\n"
      : "暂时无法查记忆,请稍后重试。\n";
  }
  if (document.state === "denied") return "当前应用没有查记忆权限。\n";
  if (document.state === "invalid") return "查记忆返回了无法识别的结果。\n";
  if (document.state === "rejected") {
    return `查记忆被拒绝(${document.code}),请检查参数。\n`;
  }
  const lines = [
    document.state === "empty"
      ? "没有查到相关记忆。"
      : document.state === "partial"
        ? "查到以下内容,部分内容还在整理中:"
        : "查到以下相关内容:",
  ];
  // A raw hit is an excerpt of an original conversation, not a distilled
  // memory; say which one each line is so it is not read as a conclusion.
  for (const item of document.items) {
    const label =
      item.kind === "raw"
        ? `[原始对话摘录 · ${String(item.source)}]`
        : "[记忆]";
    lines.push(`- ${label} ${String(item.content)}`);
  }
  if (document.truncated) lines.push("结果已按请求预算截断。");
  return `${lines.join("\n")}\n`;
}

function validateContextResponse(
  value: unknown,
  request: ContextSearchInput,
): ContextSearchDocument | null {
  const response = record(value);
  if (
    response?.schema_version !== 2 ||
    !oneOf(response.state, ["grounded", "empty", "partial", "unavailable"]) ||
    !boundedText(response.request_id, 64) ||
    !Array.isArray(response.items) ||
    response.items.length > request.limit ||
    !integer(response.used_characters, 0, request.character_budget) ||
    typeof response.truncated !== "boolean" ||
    !number(response.total_ms, 0)
  ) {
    return null;
  }
  const requested = new Set(request.kinds);
  const items: Array<Record<string, unknown>> = [];
  let characters = 0;
  for (const itemValue of response.items) {
    const item = validateItem(itemValue, request);
    if (!item || !requested.has(item.kind as "raw" | "memory")) return null;
    items.push(item);
    characters += characterCount(item.content);
  }
  if (characters !== response.used_characters) return null;
  if (response.state === "empty" && items.length !== 0) return null;
  return {
    schema_version: 2,
    product: PRODUCT,
    state: response.state,
    request_id: response.request_id as string,
    items,
    used_characters: response.used_characters as number,
    truncated: response.truncated,
    total_ms: response.total_ms as number,
  };
}

function validateItem(
  value: unknown,
  request: ContextSearchInput,
): Record<string, unknown> | null {
  const item = record(value);
  if (
    !item ||
    !oneOf(item.kind, CONTEXT_KINDS) ||
    boundedText(item.content, 20_000, true) === null ||
    !number(item.score, 0) ||
    (item.score as number) > 1 ||
    typeof item.truncated !== "boolean"
  ) {
    return null;
  }
  if (item.kind === "memory") {
    if (
      !boundedText(item.memory_id, 512) ||
      boundedText(item.layer, 64, true) === null ||
      boundedText(item.status, 32, true) === null ||
      !optionalText(item.source, 128) ||
      !optionalText(item.updated_at, 64)
    ) {
      return null;
    }
    return {
      kind: "memory",
      memory_id: item.memory_id,
      content: item.content,
      layer: item.layer,
      status: item.status,
      source: item.source ?? null,
      updated_at: item.updated_at ?? null,
      score: item.score,
      truncated: item.truncated,
    };
  }
  if (
    !boundedText(item.raw_id, 512) ||
    !boundedText(item.source, 128) ||
    (request.raw_source_ids !== undefined &&
      !request.raw_source_ids.includes(item.source as string)) ||
    !boundedText(item.session_id, 512) ||
    !optionalText(item.memory_at, 64)
  ) {
    return null;
  }
  return {
    kind: "raw",
    raw_id: item.raw_id,
    content: item.content,
    source: item.source,
    session_id: item.session_id,
    memory_at: item.memory_at ?? null,
    score: item.score,
    truncated: item.truncated,
  };
}

function failed(
  outcome: Exclude<ReadOutcome<unknown>, { state: "ok" }>,
): ContextSearchDocument {
  return {
    schema_version: 2,
    product: PRODUCT,
    state: outcome.state,
    code: outcome.code,
    items: [],
  };
}

function record(value: unknown): Record<string, unknown> | null {
  return value !== null && typeof value === "object" && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : null;
}

/**
 * Count characters the way Core does. Python's len() counts Unicode code
 * points; String.prototype.length counts UTF-16 code units, so an emoji outside
 * the BMP is one character to Core and two here. Comparing the two totals made
 * every response containing an emoji fail the used_characters cross-check and
 * surface as response_invalid.
 */
function characterCount(value: unknown): number {
  return Array.from(String(value)).length;
}

function boundedText(
  value: unknown,
  maximum: number,
  allowEmpty = false,
): string | null {
  return typeof value === "string" &&
    value.length <= maximum &&
    (allowEmpty || value.length > 0)
    ? value
    : null;
}

function integer(value: unknown, minimum: number, maximum = Infinity): boolean {
  return (
    Number.isSafeInteger(value) &&
    (value as number) >= minimum &&
    (value as number) <= maximum
  );
}

function number(value: unknown, minimum: number): boolean {
  return (
    typeof value === "number" && Number.isFinite(value) && value >= minimum
  );
}

function oneOf<const T extends readonly string[]>(
  value: unknown,
  values: T,
): value is T[number] {
  return typeof value === "string" && values.includes(value as T[number]);
}

function optionalText(value: unknown, maximum: number): boolean {
  return (
    value === null ||
    value === undefined ||
    boundedText(value, maximum) !== null
  );
}