@downcity/plugins 1.0.4

package/src/memory/runtime/Flush.ts

@@ -0,0 +1,83 @@
+/**
+ * Memory Flush（手动刷写）。
+ *
+ * 关键点（中文）
+ * - 首版使用确定性规则，不依赖额外模型调用。
+ * - 仅提取最近消息的可读文本并落盘到 daily 记忆。
+ */
+
+import type { UIDataTypes, UIMessagePart, UITools } from "ai";
+import { isTextUIPart } from "ai";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  MemoryFlushPayload,
+  MemoryFlushResponse,
+} from "@/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/memory/runtime/Search.ts

@@ -0,0 +1,330 @@
+/**
+ * Memory Search 运行时。
+ *
+ * 关键点（中文）
+ * - 直接扫描 Markdown 文件，不依赖额外索引库。
+ * - 统一收敛检索、分块、打分与状态统计逻辑。
+ */
+
+import fs from "node:fs/promises";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  MemorySearchPayload,
+  MemorySearchResponse,
+  MemorySearchResultItem,
+  MemorySourceStat,
+  MemoryStatusResponse,
+} from "@/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 plugin 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/`.",
+    };
+  }
+}

package/src/memory/runtime/Store.ts

@@ -0,0 +1,198 @@
+/**
+ * Memory Store（文件与运行态管理）。
+ *
+ * 关键点（中文）
+ * - 管理 Memory service 的最小运行时状态。
+ * - 统一管理 memory 源文件枚举。
+ * - 不承载检索算法，检索在 Search 模块。
+ * - 新版本不再使用 module-global state，状态归属 MemoryService 实例。
+ */
+
+import type { Dirent } from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  MemoryDefaults,
+  MemorySourceType,
+} from "@/memory/types/Memory.js";
+
+export const MEMORY_DEFAULTS: MemoryDefaults = {
+  maxResults: 6,
+  minScore: 0.35,
+  maxInjectedChars: 4000,
+};
+
+export type MemorySourceFile = {
+  /**
+   * 来源分类。
+   */
+  source: MemorySourceType;
+  /**
+   * 绝对路径。
+   */
+  absPath: string;
+  /**
+   * 相对项目根目录路径。
+   */
+  relPath: string;
+};
+
+export type MemoryRuntimeState = {
+  /**
+   * 项目根目录。
+   */
+  rootPath: string;
+  /**
+   * Memory 是否启用。
+   */
+  enabled: boolean;
+};
+
+function normalizeRelPath(rootPath: string, absPath: string): string {
+  return path.relative(rootPath, absPath).replace(/\\/g, "/");
+}
+
+function isMarkdownPath(filePath: string): boolean {
+  return filePath.toLowerCase().endsWith(".md");
+}
+
+async function pathExists(absPath: string): Promise<boolean> {
+  try {
+    await fsp.access(absPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listMarkdownFilesRecursively(dirPath: string): Promise<string[]> {
+  const out: string[] = [];
+  let entries: Dirent[] = [];
+  try {
+    entries = await fsp.readdir(dirPath, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const abs = path.join(dirPath, entry.name);
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      out.push(...(await listMarkdownFilesRecursively(abs)));
+      continue;
+    }
+    if (!entry.isFile() || !isMarkdownPath(abs)) {
+      continue;
+    }
+    out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * 枚举 memory 源文件。
+ */
+export async function listMemorySourceFiles(
+  rootPath: string,
+): Promise<MemorySourceFile[]> {
+  const out: MemorySourceFile[] = [];
+  const longterm = path.join(rootPath, ".downcity", "memory", "MEMORY.md");
+  if (await pathExists(longterm)) {
+    out.push({
+      source: "longterm",
+      absPath: longterm,
+      relPath: normalizeRelPath(rootPath, longterm),
+    });
+  }
+
+  const dailyDir = path.join(rootPath, ".downcity", "memory", "daily");
+  for (const abs of await listMarkdownFilesRecursively(dailyDir)) {
+    out.push({
+      source: "daily",
+      absPath: abs,
+      relPath: normalizeRelPath(rootPath, abs),
+    });
+  }
+
+  const sessionRootDir = path.join(rootPath, ".downcity", "session");
+  let sessions: Dirent[] = [];
+  try {
+    sessions = await fsp.readdir(sessionRootDir, { withFileTypes: true });
+  } catch {
+    sessions = [];
+  }
+  for (const sessionDir of sessions) {
+    if (!sessionDir.isDirectory() || sessionDir.isSymbolicLink()) {
+      continue;
+    }
+    const workingPath = path.join(
+      sessionRootDir,
+      sessionDir.name,
+      "memory",
+      "working.md",
+    );
+    if (!(await pathExists(workingPath))) {
+      continue;
+    }
+    out.push({
+      source: "working",
+      absPath: workingPath,
+      relPath: normalizeRelPath(rootPath, workingPath),
+    });
+  }
+
+  return out;
+}
+
+/**
+ * 判断 Memory 功能是否启用（默认 true）。
+ */
+export function isMemoryEnabled(context: AgentContext): boolean {
+  const enabled = context.config?.context?.memory?.enabled;
+  return enabled !== false;
+}
+
+/**
+ * 创建一个新的 memory plugin state。
+ *
+ * 关键点（中文）
+ * - 每个 `MemoryPlugin` 实例都持有自己的 state。
+ * - 不再按 rootPath 落到模块级 Map，避免 plugin runtime 实例之间共享状态。
+ */
+export function createMemoryRuntimeState(
+  context: AgentContext,
+): MemoryRuntimeState {
+  return {
+    rootPath: context.rootPath,
+    enabled: isMemoryEnabled(context),
+  };
+}
+
+/**
+ * 启动 memory 运行时。
+ *
+ * 关键点（中文）
+ * - Markdown-only 方案下不再维护后台索引同步。
+ * - 这里只负责根据配置刷新 enabled 状态。
+ */
+export async function startMemoryRuntime(
+  context: AgentContext,
+  state: MemoryRuntimeState,
+): Promise<void> {
+  state.enabled = isMemoryEnabled(context);
+  if (!state.enabled) {
+    context.logger.info("[memory] disabled by config");
+    return;
+  }
+}
+
+/**
+ * 停止 memory 运行时。
+ */
+export async function stopMemoryRuntime(
+  _state: MemoryRuntimeState,
+): Promise<void> {
+  void _state;
+}