@downcity/plugins 1.0.59 → 1.0.61

package/src/memory/Action.ts

@@ -1,21 +1,28 @@
 /**
- * Memory Service Action 逻辑。
+ * Memory Plugin action 逻辑。
  *
  * 关键点（中文）
- * - 只处理业务动作，不包含 CLI/API 参数映射细节。
- * - 所有动作统一返回结构化结果，失败不抛给上层。
+ * - action 面向 agent 的记忆语义：search/read/remember/digest/revise。
+ * - 原始证据先进入 sources，长期知识进入 wiki。
+ * - LLM digest/revise 能力由 MemoryPlugin constructor 注入。
  */
 
+import type { UIDataTypes, UIMessagePart, UITools } from "ai";
+import { isTextUIPart } from "ai";
 import type { PluginActionResult } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 import type {
-  MemoryFlushPayload,
-  MemoryGetPayload,
+  MemoryDigestPayload,
+  MemoryDigestResponse,
+  MemoryPluginOptions,
+  MemoryReadPayload,
+  MemoryRememberPayload,
+  MemoryRememberResponse,
+  MemoryRevisePayload,
+  MemoryReviseResponse,
   MemorySearchPayload,
-  MemoryStorePayload,
 } from "@/memory/types/Memory.js";
-import { flushMemory } from "./runtime/Flush.js";
 import {
   collectMemoryStatus,
   searchMemory,
@@ -24,7 +31,93 @@ import {
   MEMORY_DEFAULTS,
   type MemoryRuntimeState,
 } from "./runtime/Store.js";
-import { getMemory, storeMemory } from "./runtime/Writer.js";
+import {
+  appendManualSource,
+  appendMemoryRevision,
+  appendWikiPage,
+  readMemory,
+  readWikiIndex,
+  writeSessionSource,
+  writeWikiPage,
+} from "./runtime/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}`;
+}
+
+function readDigestPages(result: Awaited<ReturnType<NonNullable<MemoryPluginOptions["digest"]>>>): {
+  pages: Array<{ path?: string; title?: string; content: string; tags?: string[] }>;
+  summary?: string;
+} {
+  if (typeof result === "string") {
+    return {
+      pages: [{ title: "Memory Digest", content: result, tags: ["memory", "digest"] }],
+    };
+  }
+  return {
+    pages: result.pages,
+    summary: result.summary,
+  };
+}
+
+function readReviseResult(
+  result: Awaited<ReturnType<NonNullable<MemoryPluginOptions["revise"]>>>,
+  fallbackPath: string,
+): { path: string; content: string; summary?: string } {
+  if (typeof result === "string") {
+    return {
+      path: fallbackPath,
+      content: result,
+    };
+  }
+  return {
+    path: result.path || fallbackPath,
+    content: result.content,
+    summary: result.summary,
+  };
+}
+
+function slugify(value: string): string {
+  const text = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+  return text || "inbox";
+}
+
+function toWikiMemoryPath(value: string): string {
+  const clean = String(value || "").replace(/\\/g, "/").replace(/^\/+/, "").trim();
+  if (!clean) return ".downcity/memory/wiki/inbox.md";
+  if (clean.startsWith(".downcity/memory/wiki/")) {
+    return clean.toLowerCase().endsWith(".md") ? clean : `${clean}.md`;
+  }
+  const withoutPrefix = clean.replace(/^wiki\//, "");
+  const withExt = withoutPrefix.toLowerCase().endsWith(".md")
+    ? withoutPrefix
+    : `${withoutPrefix}.md`;
+  return `.downcity/memory/wiki/${withExt}`;
+}
 
 /**
  * status action。
@@ -70,14 +163,14 @@ export async function searchMemoryAction(
 }
 
 /**
- * get action。
+ * read action。
  */
-export async function getMemoryAction(
+export async function readMemoryAction(
   context: AgentContext,
-  payload: MemoryGetPayload,
+  payload: MemoryReadPayload,
 ): Promise<PluginActionResult<JsonValue>> {
   try {
-    const data = await getMemory(context, payload);
+    const data = await readMemory(context, payload);
     return { success: true, data: data as unknown as JsonValue };
   } catch (error) {
     return {
@@ -88,16 +181,65 @@ export async function getMemoryAction(
 }
 
 /**
- * store action。
+ * remember action。
  */
-export async function storeMemoryAction(
+export async function rememberMemoryAction(
   context: AgentContext,
-  state: MemoryRuntimeState,
-  payload: MemoryStorePayload,
+  options: MemoryPluginOptions,
+  payload: MemoryRememberPayload,
 ): Promise<PluginActionResult<JsonValue>> {
   try {
-    const data = await storeMemory(context, state, payload);
-    return { success: true, data: data as unknown as JsonValue };
+    const content = String(payload.content || "").trim();
+    if (!content) {
+      throw new Error("content is required");
+    }
+    const source = await appendManualSource(context, content, payload.source);
+    const targetPath = toWikiMemoryPath(payload.path || slugify(payload.topic || "inbox"));
+
+    if (options.revise) {
+      const current = await readMemory(context, { path: targetPath }).catch(() => ({
+        path: targetPath,
+        text: "",
+      }));
+      const revised = readReviseResult(
+        await options.revise({
+          rootPath: context.rootPath,
+          path: targetPath,
+          currentContent: current.text,
+          instruction: "Integrate this new memory into the wiki page. Deduplicate and keep it concise.",
+          evidence: `${content}\n\nSource: ${source.path}`,
+        }),
+        targetPath,
+      );
+      const written = await writeWikiPage(context, {
+        path: revised.path,
+        title: payload.topic,
+        content: revised.content,
+        tags: ["memory"],
+      });
+      const response: MemoryRememberResponse = {
+        sourcePath: source.path,
+        wikiPath: written.path,
+        mode: "revised",
+        writtenChars: written.writtenChars,
+        summary: revised.summary,
+      };
+      return { success: true, data: response as unknown as JsonValue };
+    }
+
+    const written = await appendWikiPage(context, {
+      path: targetPath,
+      title: payload.topic || "Memory Inbox",
+      content,
+      sourcePath: source.path,
+    });
+    const response: MemoryRememberResponse = {
+      sourcePath: source.path,
+      wikiPath: written.path,
+      mode: "appended",
+      writtenChars: written.writtenChars,
+    };
+    return { success: true, data: response as unknown as JsonValue };
   } catch (error) {
     return {
       success: false,
@@ -107,16 +249,135 @@ export async function storeMemoryAction(
 }
 
 /**
- * flush action。
+ * digest action。
  */
-export async function flushMemoryAction(
+export async function digestMemoryAction(
   context: AgentContext,
-  state: MemoryRuntimeState,
-  payload: MemoryFlushPayload,
-): Promise<PluginActionResult> {
+  options: MemoryPluginOptions,
+  payload: MemoryDigestPayload,
+): Promise<PluginActionResult<JsonValue>> {
   try {
-    const data = await flushMemory(context, state, payload);
-    return { success: true, data: data as unknown as JsonValue };
+    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 transcript =
+      lines.length > 0
+        ? lines.join("\n\n")
+        : "本次 digest 未找到可写入的用户/助手文本内容。";
+    const sourceText = [
+      `Window: ${start}-${Math.max(start, total - 1)}`,
+      "",
+      transcript,
+    ].join("\n");
+    const source = await writeSessionSource(context, sessionId, sourceText);
+
+    if (options.digest) {
+      const wikiIndex = await readWikiIndex(context);
+      const digested = readDigestPages(
+        await options.digest({
+          rootPath: context.rootPath,
+          sourceText,
+          sourcePath: source.path,
+          sessionId,
+          wikiIndex,
+        }),
+      );
+      const wikiPaths: string[] = [];
+      for (const page of digested.pages) {
+        const written = await writeWikiPage(context, page);
+        wikiPaths.push(written.path);
+      }
+      const response: MemoryDigestResponse = {
+        sourcePath: source.path,
+        wikiPaths,
+        messageCount: lines.length,
+        mode: "digested",
+        summary: digested.summary,
+      };
+      return { success: true, data: response as unknown as JsonValue };
+    }
+
+    const written = await appendWikiPage(context, {
+      path: "session-digests",
+      title: "Session Digests",
+      content: sourceText,
+      sourcePath: source.path,
+    });
+    const response: MemoryDigestResponse = {
+      sourcePath: source.path,
+      wikiPaths: [written.path],
+      messageCount: lines.length,
+      mode: "archived",
+    };
+    return { success: true, data: response as unknown as JsonValue };
+  } catch (error) {
+    return {
+      success: false,
+      error: String(error),
+    };
+  }
+}
+
+/**
+ * revise action。
+ */
+export async function reviseMemoryAction(
+  context: AgentContext,
+  options: MemoryPluginOptions,
+  payload: MemoryRevisePayload,
+): Promise<PluginActionResult<JsonValue>> {
+  try {
+    const targetPath = toWikiMemoryPath(String(payload.path || "").trim());
+    if (!targetPath) {
+      throw new Error("path is required");
+    }
+    const instruction = String(payload.instruction || "").trim();
+    if (!instruction) {
+      throw new Error("instruction is required");
+    }
+
+    if (options.revise) {
+      const current = await readMemory(context, { path: targetPath }).catch(() => ({
+        path: targetPath,
+        text: "",
+      }));
+      const revised = readReviseResult(
+        await options.revise({
+          rootPath: context.rootPath,
+          path: targetPath,
+          currentContent: current.text,
+          instruction,
+          evidence: String(payload.evidence || ""),
+        }),
+        targetPath,
+      );
+      const written = await writeWikiPage(context, {
+        path: revised.path,
+        content: revised.content,
+        tags: ["memory"],
+      });
+      const response: MemoryReviseResponse = {
+        path: written.path,
+        mode: "revised",
+        writtenChars: written.writtenChars,
+        summary: revised.summary,
+      };
+      return { success: true, data: response as unknown as JsonValue };
+    }
+
+    const response = await appendMemoryRevision(context, payload);
+    return { success: true, data: response as unknown as JsonValue };
   } catch (error) {
     return {
       success: false,
@@ -143,5 +404,11 @@ export function toSearchPayload(input: Record<string, unknown>): MemorySearchPay
         : typeof input.minScore === "string"
           ? Number(input.minScore)
           : MEMORY_DEFAULTS.minScore,
+    includeSources:
+      typeof input.includeSources === "boolean"
+        ? input.includeSources
+        : typeof input.includeSources === "string"
+          ? input.includeSources === "true"
+          : undefined,
   };
 }

package/src/memory/MemoryPlugin.ts

@@ -1,10 +1,10 @@
 /**
- * MemoryPlugin：memory plugin 的类实现。
+ * MemoryPlugin：agent 的长期记忆 plugin。
  *
  * 关键点（中文）
- * - memory plugin state 现在归属于 plugin 实例。
- * - agent 持有 MemoryPlugin 实例，从而天然形成 per-agent 状态边界。
- * - 运行态只在实例内部缓存，不再放到模块级 Map。
+ * - 对外仍然是 MemoryPlugin，内部使用 LLM Wiki 方式组织知识。
+ * - constructor 注入 digest/revise 能力，plugin 不绑定具体 LLM 服务。
+ * - action 面向 agent 语义，而不是暴露底层文件写入细节。
  */
 
 import type { Command } from "commander";
@@ -13,20 +13,20 @@ import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/
 import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
 import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
 import {
-  flushMemoryAction,
-  getMemoryAction,
+  digestMemoryAction,
+  readMemoryAction,
+  rememberMemoryAction,
+  reviseMemoryAction,
   searchMemoryAction,
   statusMemoryAction,
-  storeMemoryAction,
 } from "./Action.js";
 import {
   createMemoryRuntimeState,
-  startMemoryRuntime,
-  stopMemoryRuntime,
   type MemoryRuntimeState,
 } from "./runtime/Store.js";
 import { buildMemoryPluginSystemText } from "./runtime/SystemProvider.js";
 import { ensureMemoryDirectories } from "./runtime/Writer.js";
+import type { MemoryPluginOptions } from "./types/Memory.js";
 
 function parsePositiveInteger(value: string): number {
   const text = String(value || "").trim();
@@ -74,6 +74,11 @@ function readOptionalNumber(body: JsonObject, key: string): number | undefined {
   return typeof value === "number" ? value : undefined;
 }
 
+function readOptionalBoolean(body: JsonObject, key: string): boolean | undefined {
+  const value = body[key];
+  return typeof value === "boolean" ? value : undefined;
+}
+
 /**
  * Memory plugin 类实现。
  */
@@ -88,6 +93,13 @@ export class MemoryPlugin extends BasePlugin {
    */
   public runtimeState: MemoryRuntimeState | null = null;
 
+  /**
+   * 创建 MemoryPlugin。
+   */
+  constructor(private readonly options: MemoryPluginOptions = {}) {
+    super();
+  }
+
   /**
    * 当前 plugin 的 system 文本提供器。
    */
@@ -101,12 +113,9 @@ export class MemoryPlugin extends BasePlugin {
   readonly lifecycle = {
     start: async (context: AgentContext): Promise<void> => {
       await ensureMemoryDirectories(context.rootPath);
-      const state = this.getOrCreateRuntimeState(context);
-      await startMemoryRuntime(context, state);
+      this.getOrCreateRuntimeState(context);
     },
     stop: async (): Promise<void> => {
-      if (!this.runtimeState) return;
-      await stopMemoryRuntime(this.runtimeState);
       this.runtimeState = null;
     },
   };
@@ -117,7 +126,7 @@ export class MemoryPlugin extends BasePlugin {
   readonly actions: PluginActions = {
     status: {
       command: {
-        description: "查看 memory 状态（backend/files/chunks）",
+        description: "查看 memory wiki 状态（wiki/source/working）",
         mapInput() {
           return {};
         },
@@ -129,12 +138,13 @@ export class MemoryPlugin extends BasePlugin {
     },
     search: {
       command: {
-        description: "检索记忆片段",
+        description: "检索 memory wiki",
         configure(command: Command) {
           command
             .argument("<query>")
             .option("--max-results <number>", "返回条数上限", parsePositiveInteger)
-            .option("--min-score <number>", "最小相关分数", parseNumber);
+            .option("--min-score <number>", "最小相关分数", parseNumber)
+            .option("--include-sources", "同时检索原始 source 层");
         },
         mapInput({ args, opts }) {
           const payload: JsonObject = {
@@ -146,6 +156,9 @@ export class MemoryPlugin extends BasePlugin {
           if (typeof opts.minScore === "number") {
             payload.minScore = opts.minScore;
           }
+          if (opts.includeSources === true) {
+            payload.includeSources = true;
+          }
           return payload;
         },
       },
@@ -156,12 +169,13 @@ export class MemoryPlugin extends BasePlugin {
           query: readString(body, "query"),
           maxResults: readOptionalNumber(body, "maxResults"),
           minScore: readOptionalNumber(body, "minScore"),
+          includeSources: readOptionalBoolean(body, "includeSources"),
         });
       },
     },
-    get: {
+    read: {
       command: {
-        description: "读取记忆文件片段",
+        description: "读取 memory wiki/source 文件片段",
         configure(command: Command) {
           command
             .argument("<memoryPath>", "记忆文件路径（相对项目根目录）")
@@ -183,52 +197,52 @@ export class MemoryPlugin extends BasePlugin {
       },
       execute: async (params) => {
         const body = readBodyObject(params.payload);
-        return await getMemoryAction(params.context, {
+        return await readMemoryAction(params.context, {
           path: readString(body, "path"),
           from: readOptionalNumber(body, "from"),
           lines: readOptionalNumber(body, "lines"),
         });
       },
     },
-    store: {
+    remember: {
       command: {
-        description: "显式写入 memory（longterm/daily/working）",
+        description: "把事实/偏好/决策记入 memory wiki",
         configure(command: Command) {
           command
-            .requiredOption("--content <text>", "写入内容")
-            .option("--target <target>", "写入层（longterm|daily|working）")
-            .option("--session-id <sessionId>", "working 目标必填");
+            .requiredOption("--content <text>", "需要记住的内容")
+            .option("--topic <topic>", "记忆主题")
+            .option("--wiki-path <path>", "目标 wiki page 路径")
+            .option("--source <source>", "来源说明");
         },
         mapInput({ opts }) {
           const payload: JsonObject = {
             content: String(opts.content || ""),
           };
-          if (typeof opts.target === "string") {
-            payload.target = String(opts.target).trim();
+          if (typeof opts.topic === "string") {
+            payload.topic = String(opts.topic).trim();
           }
-          if (typeof opts.sessionId === "string") {
-            payload.sessionId = String(opts.sessionId).trim();
+          if (typeof opts.wikiPath === "string") {
+            payload.path = String(opts.wikiPath).trim();
+          }
+          if (typeof opts.source === "string") {
+            payload.source = String(opts.source).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, {
+        return await rememberMemoryAction(params.context, this.options, {
           content: readString(body, "content"),
-          target:
-            target === "longterm" || target === "daily" || target === "working"
-              ? target
-              : undefined,
-          sessionId: readOptionalString(body, "sessionId"),
+          topic: readOptionalString(body, "topic"),
+          path: readOptionalString(body, "path"),
+          source: readOptionalString(body, "source"),
         });
       },
     },
-    flush: {
+    digest: {
       command: {
-        description: "将当前会话最近消息刷写到 daily memory",
+        description: "把 session 提炼进 memory wiki",
         configure(command: Command) {
           command
             .requiredOption("--session-id <sessionId>", "会话 ID")
@@ -246,13 +260,41 @@ export class MemoryPlugin extends BasePlugin {
       },
       execute: async (params) => {
         const body = readBodyObject(params.payload);
-        const state = this.getOrCreateRuntimeState(params.context);
-        return await flushMemoryAction(params.context, state, {
+        return await digestMemoryAction(params.context, this.options, {
           sessionId: readString(body, "sessionId"),
           maxMessages: readOptionalNumber(body, "maxMessages"),
         });
       },
     },
+    revise: {
+      command: {
+        description: "基于新证据修订 memory wiki page",
+        configure(command: Command) {
+          command
+            .argument("<memoryPath>", "目标 wiki page 路径")
+            .requiredOption("--instruction <text>", "修订指令")
+            .option("--evidence <text>", "新证据");
+        },
+        mapInput({ args, opts }) {
+          const payload: JsonObject = {
+            path: String(args[0] || ""),
+            instruction: String(opts.instruction || ""),
+          };
+          if (typeof opts.evidence === "string") {
+            payload.evidence = String(opts.evidence).trim();
+          }
+          return payload;
+        },
+      },
+      execute: async (params) => {
+        const body = readBodyObject(params.payload);
+        return await reviseMemoryAction(params.context, this.options, {
+          path: readString(body, "path"),
+          instruction: readString(body, "instruction"),
+          evidence: readOptionalString(body, "evidence"),
+        });
+      },
+    },
   };
 
   /**

package/src/memory/runtime/Search.ts

@@ -2,7 +2,7 @@
  * Memory Search 运行时。
  *
  * 关键点（中文）
- * - 直接扫描 Markdown 文件，不依赖额外索引库。
+ * - 直接扫描 LLM Wiki Markdown 文件，不依赖额外索引库。
  * - 统一收敛检索、分块、打分与状态统计逻辑。
  */
 
@@ -147,17 +147,20 @@ function chunkMarkdown(content: string): Array<{
   return out;
 }
 
-async function readMemoryChunks(context: AgentContext): Promise<Array<{
+async function readMemoryChunks(
+  context: AgentContext,
+  options: { includeSources?: boolean },
+): Promise<Array<{
   path: string;
-  source: "longterm" | "daily" | "working";
+  source: "wiki" | "source" | "working";
   startLine: number;
   endLine: number;
   text: string;
 }>> {
-  const files = await listMemorySourceFiles(context.rootPath);
+  const files = await listMemorySourceFiles(context.rootPath, options);
   const out: Array<{
     path: string;
-    source: "longterm" | "daily" | "working";
+    source: "wiki" | "source" | "working";
     startLine: number;
     endLine: number;
     text: string;
@@ -185,10 +188,12 @@ export async function collectMemoryStatus(
   state: MemoryRuntimeState,
 ): Promise<MemoryStatusResponse> {
   void state;
-  const files = await listMemorySourceFiles(context.rootPath);
+  const files = await listMemorySourceFiles(context.rootPath, {
+    includeSources: true,
+  });
   const sourceCounts: MemorySourceStat[] = [
-    { source: "longterm", files: 0, chunks: 0 },
-    { source: "daily", files: 0, chunks: 0 },
+    { source: "wiki", files: 0, chunks: 0 },
+    { source: "source", files: 0, chunks: 0 },
     { source: "working", files: 0, chunks: 0 },
   ];
 
@@ -257,7 +262,9 @@ export async function searchMemory(
   );
 
   try {
-    const results = (await readMemoryChunks(context))
+    const results = (await readMemoryChunks(context, {
+      includeSources: payload.includeSources,
+    }))
       .map((chunk) => {
         const score = buildSnippetScore(chunk.text, tokens);
         const citation =