@downcity/agent 1.1.23 → 1.1.32

package/src/service/builtins/memory/MemoryService.ts

@@ -1,270 +0,0 @@
-/**
- * MemoryService：memory service 的类实现。
- *
- * 关键点（中文）
- * - memory service state 现在归属于 service 实例。
- * - agent 持有 MemoryService 实例，从而天然形成 per-agent 状态边界。
- * - 运行态只在实例内部缓存，不再放到模块级 Map。
- */
-
-import type { Command } from "commander";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ServiceActions } from "@/service/types/Service.js";
-import { BaseService } from "@/service/builtins/BaseService.js";
-import {
-  flushMemoryAction,
-  getMemoryAction,
-  searchMemoryAction,
-  statusMemoryAction,
-  storeMemoryAction,
-} from "./Action.js";
-import {
-  createMemoryRuntimeState,
-  isMemoryEnabled,
-  startMemoryRuntime,
-  stopMemoryRuntime,
-  type MemoryRuntimeState,
-} from "./runtime/Store.js";
-import { buildMemoryServiceSystemText } from "./runtime/SystemProvider.js";
-import { ensureMemoryDirectories } from "./runtime/Writer.js";
-
-function parsePositiveInteger(value: string): number {
-  const text = String(value || "").trim();
-  if (!/^\d+$/.test(text)) {
-    throw new Error(`Invalid positive integer: ${value}`);
-  }
-  const num = Number(text);
-  if (!Number.isFinite(num) || num < 1) {
-    throw new Error(`Invalid positive integer: ${value}`);
-  }
-  return num;
-}
-
-function parseNumber(value: string): number {
-  const text = String(value || "").trim();
-  if (!text) {
-    throw new Error("number is required");
-  }
-  const num = Number(text);
-  if (!Number.isFinite(num)) {
-    throw new Error(`Invalid number: ${value}`);
-  }
-  return num;
-}
-
-function readBodyObject(rawBody: JsonValue): JsonObject {
-  if (!rawBody || typeof rawBody !== "object" || Array.isArray(rawBody)) {
-    return {};
-  }
-  return rawBody as JsonObject;
-}
-
-function readString(body: JsonObject, key: string): string {
-  const value = body[key];
-  return typeof value === "string" ? value : "";
-}
-
-function readOptionalString(body: JsonObject, key: string): string | undefined {
-  const value = body[key];
-  return typeof value === "string" ? value : undefined;
-}
-
-function readOptionalNumber(body: JsonObject, key: string): number | undefined {
-  const value = body[key];
-  return typeof value === "number" ? value : undefined;
-}
-
-/**
- * Memory service 类实现。
- */
-export class MemoryService extends BaseService {
-  /**
-   * service 名称。
-   */
-  readonly name = "memory";
-
-  /**
-   * 当前实例持有的 memory service state。
-   */
-  public runtimeState: MemoryRuntimeState | null = null;
-
-  /**
-   * 当前 service 的 system 文本提供器。
-   */
-  async system(context: AgentContext): Promise<string> {
-    return await buildMemoryServiceSystemText(context);
-  }
-
-  /**
-   * 当前 service 生命周期。
-   */
-  readonly lifecycle = {
-    start: async (context: AgentContext): Promise<void> => {
-      await ensureMemoryDirectories(context.rootPath);
-      const state = this.getOrCreateRuntimeState(context);
-      await startMemoryRuntime(context, state);
-    },
-    stop: async (): Promise<void> => {
-      if (!this.runtimeState) return;
-      await stopMemoryRuntime(this.runtimeState);
-      this.runtimeState = null;
-    },
-  };
-
-  /**
-   * 当前 service action 定义表。
-   */
-  readonly actions: ServiceActions = {
-    status: {
-      command: {
-        description: "查看 memory 状态（backend/files/chunks）",
-        mapInput() {
-          return {};
-        },
-      },
-      execute: async (params) => {
-        const state = this.getOrCreateRuntimeState(params.context);
-        return await statusMemoryAction(params.context, state);
-      },
-    },
-    search: {
-      command: {
-        description: "检索记忆片段",
-        configure(command: Command) {
-          command
-            .argument("<query>")
-            .option("--max-results <number>", "返回条数上限", parsePositiveInteger)
-            .option("--min-score <number>", "最小相关分数", parseNumber);
-        },
-        mapInput({ args, opts }) {
-          const payload: JsonObject = {
-            query: String(args[0] || ""),
-          };
-          if (typeof opts.maxResults === "number") {
-            payload.maxResults = opts.maxResults;
-          }
-          if (typeof opts.minScore === "number") {
-            payload.minScore = opts.minScore;
-          }
-          return payload;
-        },
-      },
-      execute: async (params) => {
-        const body = readBodyObject(params.payload);
-        const state = this.getOrCreateRuntimeState(params.context);
-        return await searchMemoryAction(params.context, state, {
-          query: readString(body, "query"),
-          maxResults: readOptionalNumber(body, "maxResults"),
-          minScore: readOptionalNumber(body, "minScore"),
-        });
-      },
-    },
-    get: {
-      command: {
-        description: "读取记忆文件片段",
-        configure(command: Command) {
-          command
-            .argument("<memoryPath>", "记忆文件路径（相对项目根目录）")
-            .option("--from <number>", "起始行（1-based）", parsePositiveInteger)
-            .option("--lines <number>", "读取行数", parsePositiveInteger);
-        },
-        mapInput({ args, opts }) {
-          const payload: JsonObject = {
-            path: String(args[0] || ""),
-          };
-          if (typeof opts.from === "number") {
-            payload.from = opts.from;
-          }
-          if (typeof opts.lines === "number") {
-            payload.lines = opts.lines;
-          }
-          return payload;
-        },
-      },
-      execute: async (params) => {
-        const body = readBodyObject(params.payload);
-        return await getMemoryAction(params.context, {
-          path: readString(body, "path"),
-          from: readOptionalNumber(body, "from"),
-          lines: readOptionalNumber(body, "lines"),
-        });
-      },
-    },
-    store: {
-      command: {
-        description: "显式写入 memory（longterm/daily/working）",
-        configure(command: Command) {
-          command
-            .requiredOption("--content <text>", "写入内容")
-            .option("--target <target>", "写入层（longterm|daily|working）")
-            .option("--session-id <sessionId>", "working 目标必填");
-        },
-        mapInput({ opts }) {
-          const payload: JsonObject = {
-            content: String(opts.content || ""),
-          };
-          if (typeof opts.target === "string") {
-            payload.target = String(opts.target).trim();
-          }
-          if (typeof opts.sessionId === "string") {
-            payload.sessionId = String(opts.sessionId).trim();
-          }
-          return payload;
-        },
-      },
-      execute: async (params) => {
-        const body = readBodyObject(params.payload);
-        const target = readOptionalString(body, "target");
-        const state = this.getOrCreateRuntimeState(params.context);
-        return await storeMemoryAction(params.context, state, {
-          content: readString(body, "content"),
-          target:
-            target === "longterm" || target === "daily" || target === "working"
-              ? target
-              : undefined,
-          sessionId: readOptionalString(body, "sessionId"),
-        });
-      },
-    },
-    flush: {
-      command: {
-        description: "将当前会话最近消息刷写到 daily memory",
-        configure(command: Command) {
-          command
-            .requiredOption("--session-id <sessionId>", "会话 ID")
-            .option("--max-messages <number>", "提取消息窗口", parsePositiveInteger);
-        },
-        mapInput({ opts }) {
-          const payload: JsonObject = {
-            sessionId: String(opts.sessionId || ""),
-          };
-          if (typeof opts.maxMessages === "number") {
-            payload.maxMessages = opts.maxMessages;
-          }
-          return payload;
-        },
-      },
-      execute: async (params) => {
-        const body = readBodyObject(params.payload);
-        const state = this.getOrCreateRuntimeState(params.context);
-        return await flushMemoryAction(params.context, state, {
-          sessionId: readString(body, "sessionId"),
-          maxMessages: readOptionalNumber(body, "maxMessages"),
-        });
-      },
-    },
-  };
-
-  /**
-   * 获取或创建当前实例绑定的 memory service state。
-   */
-  private getOrCreateRuntimeState(context: AgentContext): MemoryRuntimeState {
-    if (!this.runtimeState) {
-      this.runtimeState = createMemoryRuntimeState(context);
-      return this.runtimeState;
-    }
-    this.runtimeState.enabled = isMemoryEnabled(context);
-    return this.runtimeState;
-  }
-}

package/src/service/builtins/memory/runtime/Flush.ts

@@ -1,83 +0,0 @@
-/**
- * Memory Flush（手动刷写）。
- *
- * 关键点（中文）
- * - 首版使用确定性规则，不依赖额外模型调用。
- * - 仅提取最近消息的可读文本并落盘到 daily 记忆。
- */
-
-import type { UIDataTypes, UIMessagePart, UITools } from "ai";
-import { isTextUIPart } from "ai";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type {
-  MemoryFlushPayload,
-  MemoryFlushResponse,
-} from "@/service/builtins/memory/types/Memory.js";
-import type { MemoryRuntimeState } from "./Store.js";
-import { storeMemory } from "./Writer.js";
-
-type AnyUiMessagePart = UIMessagePart<UIDataTypes, UITools>;
-
-function toUiParts(message: { parts?: AnyUiMessagePart[] } | null | undefined): AnyUiMessagePart[] {
-  return Array.isArray(message?.parts) ? message.parts : [];
-}
-
-function extractReadableLine(message: {
-  role?: string;
-  parts?: AnyUiMessagePart[];
-}): string {
-  const role = String(message.role || "").toLowerCase() === "user" ? "User" : "Assistant";
-  const text = toUiParts(message)
-    .filter(isTextUIPart)
-    .map((part) => String(part.text || "").trim())
-    .filter(Boolean)
-    .join("\n")
-    .trim();
-  if (!text) {
-    return "";
-  }
-  return `${role}: ${text}`;
-}
-
-/**
- * 把当前会话最近消息刷写到 daily 记忆。
- */
-export async function flushMemory(
-  context: AgentContext,
-  state: MemoryRuntimeState,
-  payload: MemoryFlushPayload,
-): Promise<MemoryFlushResponse> {
-  const sessionId = String(payload.sessionId || "").trim();
-  if (!sessionId) {
-    throw new Error("sessionId is required");
-  }
-  const maxMessages = Number.isFinite(payload.maxMessages)
-    ? Math.max(1, Math.floor(payload.maxMessages as number))
-    : 30;
-  const historyStore = context.session.get(sessionId).getHistoryStore();
-  const total = await historyStore.size();
-  const start = Math.max(0, total - maxMessages);
-  const messages = await historyStore.slice(start, total);
-  const lines = messages
-    .map((msg) => extractReadableLine(msg))
-    .filter((line) => line.length > 0);
-  const summary =
-    lines.length > 0
-      ? lines.join("\n\n")
-      : "本次 flush 未找到可写入的用户/助手文本内容。";
-  const content = [
-    `Flush Session: ${sessionId}`,
-    `Window: ${start}-${Math.max(start, total - 1)}`,
-    "",
-    summary,
-  ].join("\n");
-  const saved = await storeMemory(context, state, {
-    content,
-    target: "daily",
-  });
-  return {
-    path: saved.path,
-    messageCount: lines.length,
-    writtenChars: saved.writtenChars,
-  };
-}

package/src/service/builtins/memory/runtime/Search.ts

@@ -1,330 +0,0 @@
-/**
- * Memory Search 运行时。
- *
- * 关键点（中文）
- * - 直接扫描 Markdown 文件，不依赖额外索引库。
- * - 统一收敛检索、分块、打分与状态统计逻辑。
- */
-
-import fs from "node:fs/promises";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type {
-  MemorySearchPayload,
-  MemorySearchResponse,
-  MemorySearchResultItem,
-  MemorySourceStat,
-  MemoryStatusResponse,
-} from "@/service/builtins/memory/types/Memory.js";
-import {
-  listMemorySourceFiles,
-  MEMORY_DEFAULTS,
-  type MemoryRuntimeState,
-} from "./Store.js";
-
-const SNIPPET_MAX_CHARS = 700;
-const CHUNK_MAX_CHARS = 1600;
-const CHUNK_OVERLAP_CHARS = 240;
-
-function clampNumber(value: number, min: number, max: number): number {
-  if (!Number.isFinite(value)) return min;
-  return Math.max(min, Math.min(max, value));
-}
-
-function normalizeText(input: string): string {
-  return String(input || "").replace(/\r\n/g, "\n");
-}
-
-function truncateText(value: string, maxChars: number): string {
-  if (value.length <= maxChars) {
-    return value;
-  }
-  return value.slice(0, maxChars);
-}
-
-function tokenizeQuery(raw: string): string[] {
-  return String(raw || "")
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}_-]+/gu, " ")
-    .split(/\s+/)
-    .map((item) => item.trim())
-    .filter(Boolean)
-    .slice(0, 12);
-}
-
-function countTokenOccurrences(text: string, token: string): number {
-  if (!token) return 0;
-  let hits = 0;
-  let start = 0;
-  while (start < text.length) {
-    const index = text.indexOf(token, start);
-    if (index < 0) break;
-    hits += 1;
-    start = index + token.length;
-  }
-  return hits;
-}
-
-function buildSnippetScore(text: string, tokens: string[]): number {
-  if (tokens.length === 0) return 0;
-  const normalized = normalizeText(text).toLowerCase();
-  let matchedTokens = 0;
-  let totalHits = 0;
-  for (const token of tokens) {
-    const hits = countTokenOccurrences(normalized, token);
-    if (hits > 0) {
-      matchedTokens += 1;
-      totalHits += Math.min(hits, 4);
-    }
-  }
-  if (matchedTokens === 0) {
-    return 0;
-  }
-  const coverageScore = matchedTokens / tokens.length;
-  const densityScore = Math.min(totalHits, tokens.length * 3) / (tokens.length * 3);
-  return Number((coverageScore * 0.75 + densityScore * 0.25).toFixed(4));
-}
-
-function chunkMarkdown(content: string): Array<{
-  startLine: number;
-  endLine: number;
-  text: string;
-}> {
-  const lines = normalizeText(content).split("\n");
-  if (lines.length === 0) {
-    return [];
-  }
-  const out: Array<{
-    startLine: number;
-    endLine: number;
-    text: string;
-  }> = [];
-  let bucket: Array<{ line: string; lineNo: number }> = [];
-  let chars = 0;
-
-  const flush = () => {
-    if (bucket.length === 0) return;
-    const startLine = bucket[0]?.lineNo ?? 1;
-    const endLine = bucket[bucket.length - 1]?.lineNo ?? startLine;
-    const text = bucket.map((item) => item.line).join("\n").trim();
-    if (!text) return;
-    out.push({
-      startLine,
-      endLine,
-      text,
-    });
-  };
-
-  const carryOverlap = () => {
-    if (bucket.length === 0 || CHUNK_OVERLAP_CHARS <= 0) {
-      bucket = [];
-      chars = 0;
-      return;
-    }
-    let acc = 0;
-    const next: Array<{ line: string; lineNo: number }> = [];
-    for (let i = bucket.length - 1; i >= 0; i -= 1) {
-      const row = bucket[i];
-      if (!row) continue;
-      acc += row.line.length + 1;
-      next.unshift(row);
-      if (acc >= CHUNK_OVERLAP_CHARS) break;
-    }
-    bucket = next;
-    chars = bucket.reduce((sum, item) => sum + item.line.length + 1, 0);
-  };
-
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i] ?? "";
-    const rowSize = line.length + 1;
-    if (bucket.length > 0 && chars + rowSize > CHUNK_MAX_CHARS) {
-      flush();
-      carryOverlap();
-    }
-    bucket.push({ line, lineNo: i + 1 });
-    chars += rowSize;
-  }
-  flush();
-  return out;
-}
-
-async function readMemoryChunks(context: AgentContext): Promise<Array<{
-  path: string;
-  source: "longterm" | "daily" | "working";
-  startLine: number;
-  endLine: number;
-  text: string;
-}>> {
-  const files = await listMemorySourceFiles(context.rootPath);
-  const out: Array<{
-    path: string;
-    source: "longterm" | "daily" | "working";
-    startLine: number;
-    endLine: number;
-    text: string;
-  }> = [];
-  for (const file of files) {
-    const content = String(await fs.readFile(file.absPath, "utf-8"));
-    for (const chunk of chunkMarkdown(content)) {
-      out.push({
-        path: file.relPath,
-        source: file.source,
-        startLine: chunk.startLine,
-        endLine: chunk.endLine,
-        text: chunk.text,
-      });
-    }
-  }
-  return out;
-}
-
-/**
- * 收集当前 memory Markdown 状态。
- */
-export async function collectMemoryStatus(
-  context: AgentContext,
-  state: MemoryRuntimeState,
-): Promise<MemoryStatusResponse> {
-  const files = await listMemorySourceFiles(context.rootPath);
-  const sourceCounts: MemorySourceStat[] = [
-    { source: "longterm", files: 0, chunks: 0 },
-    { source: "daily", files: 0, chunks: 0 },
-    { source: "working", files: 0, chunks: 0 },
-  ];
-
-  let totalChunks = 0;
-  for (const file of files) {
-    const bucket = sourceCounts.find((item) => item.source === file.source);
-    if (bucket) {
-      bucket.files += 1;
-    }
-    const content = String(await fs.readFile(file.absPath, "utf-8"));
-    const chunks = chunkMarkdown(content).length;
-    totalChunks += chunks;
-    if (bucket) {
-      bucket.chunks += chunks;
-    }
-  }
-
-  return {
-    enabled: state.enabled,
-    backend: "builtin",
-    mode: "scan",
-    files: files.length,
-    chunks: totalChunks,
-    sourceCounts,
-  };
-}
-
-/**
- * 执行检索。
- */
-export async function searchMemory(
-  context: AgentContext,
-  state: MemoryRuntimeState,
-  payload: MemorySearchPayload,
-): Promise<MemorySearchResponse> {
-  if (!state.enabled) {
-    return {
-      backend: "builtin",
-      mode: "scan",
-      results: [],
-      disabled: true,
-      error: "memory service disabled",
-      action: "Set context.memory.enabled=true or remove the config override.",
-    };
-  }
-
-  const query = String(payload.query || "").trim();
-  if (!query) {
-    return {
-      backend: "builtin",
-      mode: "scan",
-      results: [],
-    };
-  }
-
-  const tokens = tokenizeQuery(query);
-  if (tokens.length === 0) {
-    return {
-      backend: "builtin",
-      mode: "scan",
-      results: [],
-    };
-  }
-
-  const maxResults = Math.floor(
-    clampNumber(
-      Number(payload.maxResults ?? MEMORY_DEFAULTS.maxResults),
-      1,
-      20,
-    ),
-  );
-  const minScore = clampNumber(
-    Number(payload.minScore ?? MEMORY_DEFAULTS.minScore),
-    0,
-    1,
-  );
-
-  try {
-    const results = (await readMemoryChunks(context))
-      .map((chunk) => {
-        const score = buildSnippetScore(chunk.text, tokens);
-        const citation =
-          chunk.startLine === chunk.endLine
-            ? `${chunk.path}#L${chunk.startLine}`
-            : `${chunk.path}#L${chunk.startLine}-L${chunk.endLine}`;
-        return {
-          path: chunk.path,
-          source: chunk.source,
-          startLine: chunk.startLine,
-          endLine: chunk.endLine,
-          score,
-          snippet: truncateText(chunk.text, SNIPPET_MAX_CHARS),
-          citation,
-        } satisfies MemorySearchResultItem;
-      })
-      .filter((item) => item.score >= minScore)
-      .sort((left, right) => {
-        if (right.score !== left.score) {
-          return right.score - left.score;
-        }
-        if (left.path !== right.path) {
-          return left.path.localeCompare(right.path);
-        }
-        return left.startLine - right.startLine;
-      })
-      .slice(0, maxResults * 3);
-
-    let remain = Math.max(0, MEMORY_DEFAULTS.maxInjectedChars);
-    const clamped: MemorySearchResultItem[] = [];
-    for (const item of results) {
-      if (remain <= 0 || clamped.length >= maxResults) break;
-      if (item.snippet.length <= remain) {
-        clamped.push(item);
-        remain -= item.snippet.length;
-        continue;
-      }
-      clamped.push({
-        ...item,
-        snippet: item.snippet.slice(0, remain),
-      });
-      break;
-    }
-
-    return {
-      backend: "builtin",
-      mode: "scan",
-      results: clamped,
-    };
-  } catch (error) {
-    const message = String(error);
-    return {
-      backend: "builtin",
-      mode: "scan",
-      results: [],
-      disabled: true,
-      error: message,
-      action: "Check the Markdown memory files under `.downcity/memory/`.",
-    };
-  }
-}