@downcity/plugins 1.0.60 → 1.0.61

package/src/memory/types/Memory.ts

@@ -1,9 +1,10 @@
 /**
- * Memory Service 类型定义。
+ * Memory Plugin 类型定义。
  *
  * 关键点（中文）
- * - 只保留 Memory V2 所需协议。
- * - 字段注释完整，供 CLI/API/运行时统一复用。
+ * - MemoryPlugin 对 agent 暴露“记忆能力”，内部使用 LLM Wiki 方式组织知识。
+ * - `wiki` 是整理后的知识层，`source` 是原始证据层，`working` 是会话局部层。
+ * - LLM 能力只通过 constructor 注入，plugin 自身不绑定具体模型或服务。
  */
 
 import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
@@ -11,16 +12,169 @@ import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
 /**
  * 记忆来源类型。
  */
-export type MemorySourceType = "longterm" | "daily" | "working";
+export type MemorySourceType = "wiki" | "source" | "working";
 
 /**
  * 查询模式。
  *
  * 说明（中文）
- * - 当前实现直接扫描 Markdown 文件，不再维护额外索引库。
+ * - 当前实现直接扫描 Markdown 文件，不引入向量库或外部索引服务。
  */
 export type MemorySearchMode = "scan";
 
+/**
+ * MemoryPlugin constructor 参数。
+ */
+export interface MemoryPluginOptions {
+  /**
+   * 把 session 或长文本 source 提炼为 wiki page 的函数。
+   *
+   * 说明（中文）：未传时 `digest` action 会做确定性落盘，不会调用模型。
+   */
+  digest?: MemoryDigestHandler;
+
+  /**
+   * 基于新证据修订某个 wiki page 的函数。
+   *
+   * 说明（中文）：未传时 `remember`/`revise` 会追加写入，不做 LLM 重写。
+   */
+  revise?: MemoryReviseHandler;
+}
+
+/**
+ * digest handler。
+ */
+export type MemoryDigestHandler = (
+  input: MemoryDigestHandlerInput,
+) => Promise<MemoryDigestHandlerOutput | string>;
+
+/**
+ * revise handler。
+ */
+export type MemoryReviseHandler = (
+  input: MemoryReviseHandlerInput,
+) => Promise<MemoryReviseHandlerOutput | string>;
+
+/**
+ * digest handler 输入。
+ */
+export interface MemoryDigestHandlerInput {
+  /**
+   * 当前项目根目录。
+   */
+  rootPath: string;
+
+  /**
+   * 需要提炼的原始文本。
+   */
+  sourceText: string;
+
+  /**
+   * 原始文本来源路径（相对项目根目录）。
+   */
+  sourcePath: string;
+
+  /**
+   * 触发 digest 的 session id。
+   */
+  sessionId?: string;
+
+  /**
+   * 当前 wiki index 内容，方便模型决定更新哪些页面。
+   */
+  wikiIndex: string;
+}
+
+/**
+ * digest handler 输出。
+ */
+export interface MemoryDigestHandlerOutput {
+  /**
+   * 本次 digest 生成或更新的 wiki page。
+   */
+  pages: MemoryWikiPageDraft[];
+
+  /**
+   * 给调用方看的简短摘要。
+   */
+  summary?: string;
+}
+
+/**
+ * revise handler 输入。
+ */
+export interface MemoryReviseHandlerInput {
+  /**
+   * 当前项目根目录。
+   */
+  rootPath: string;
+
+  /**
+   * 要修订的 wiki page 路径（相对项目根目录）。
+   */
+  path: string;
+
+  /**
+   * 当前 page 内容；文件不存在时为空字符串。
+   */
+  currentContent: string;
+
+  /**
+   * 修订指令。
+   */
+  instruction: string;
+
+  /**
+   * 新证据或需要合入的内容。
+   */
+  evidence: string;
+}
+
+/**
+ * revise handler 输出。
+ */
+export interface MemoryReviseHandlerOutput {
+  /**
+   * 修订后的 wiki page 路径；未传时沿用输入 path。
+   */
+  path?: string;
+
+  /**
+   * 修订后的完整 Markdown 内容。
+   */
+  content: string;
+
+  /**
+   * 给调用方看的简短摘要。
+   */
+  summary?: string;
+}
+
+/**
+ * 待写入 wiki 的页面草稿。
+ */
+export interface MemoryWikiPageDraft {
+  /**
+   * 目标路径；可传 `.downcity/memory/wiki/foo.md` 或 `foo.md`。
+   */
+  path?: string;
+
+  /**
+   * 页面标题。
+   */
+  title?: string;
+
+  /**
+   * 完整 Markdown 内容。
+   */
+  content: string;
+
+  /**
+   * 页面标签。
+   */
+  tags?: string[];
+}
+
 /**
  * 单条记忆检索结果。
  */
@@ -29,28 +183,34 @@ export interface MemorySearchResultItem {
    * 片段来源路径（相对项目根目录）。
    */
   path: string;
+
   /**
    * 片段起始行号（1-based）。
    */
   startLine: number;
+
   /**
    * 片段结束行号（1-based）。
    */
   endLine: number;
+
   /**
    * 归一化分数（0~1，越高越相关）。
    */
   score: number;
+
   /**
    * 返回给模型/用户的片段文本（已按预算裁剪）。
    */
   snippet: string;
+
   /**
-   * 记忆来源分类（长期/每日/工作记忆）。
+   * 记忆来源分类。
    */
   source: MemorySourceType;
+
   /**
-   * 引用标记（例如：`.downcity/memory/MEMORY.md#L12-L20`）。
+   * 引用标记（例如：`.downcity/memory/wiki/plugin-system.md#L12-L20`）。
    */
   citation: string;
 }
@@ -63,14 +223,21 @@ export interface MemorySearchPayload {
    * 查询语句。
    */
   query: string;
+
   /**
    * 可选返回条数上限，未传使用内置默认值。
    */
   maxResults?: number;
+
   /**
    * 可选分数阈值，未传使用内置默认值。
    */
   minScore?: number;
+
+  /**
+   * 是否检索原始 source 层；默认只检索 wiki 层和 working 层。
+   */
+  includeSources?: boolean;
 }
 
 /**
@@ -81,18 +248,22 @@ export interface MemorySearchResponse {
    * 返回结果集合。
    */
   results: MemorySearchResultItem[];
+
   /**
    * 当前检索模式。
    */
   mode: MemorySearchMode;
+
   /**
    * 当前后端标识。
    */
   backend: "builtin";
+
   /**
    * 错误原因文本（失败场景）。
    */
   error?: string;
+
   /**
    * 建议动作（失败场景）。
    */
@@ -102,15 +273,17 @@ export interface MemorySearchResponse {
 /**
  * 读取记忆片段请求。
  */
-export interface MemoryGetPayload {
+export interface MemoryReadPayload {
   /**
    * 相对项目根目录的目标路径。
    */
   path: string;
+
   /**
    * 可选起始行（1-based）。
    */
   from?: number;
+
   /**
    * 可选读取行数。
    */
@@ -120,15 +293,17 @@ export interface MemoryGetPayload {
 /**
  * 读取记忆片段响应。
  */
-export interface MemoryGetResponse {
+export interface MemoryReadResponse {
   /**
    * 目标路径（回显）。
    */
   path: string;
+
   /**
    * 读取内容；文件缺失时为空字符串。
    */
   text: string;
+
   /**
    * 文件不存在时为 true。
    */
@@ -136,49 +311,69 @@ export interface MemoryGetResponse {
 }
 
 /**
- * 显式写入请求。
+ * remember 请求。
  */
-export interface MemoryStorePayload {
+export interface MemoryRememberPayload {
   /**
-   * 要写入的文本内容。
+   * 需要记住的内容。
    */
   content: string;
+
   /**
-   * 目标记忆层，默认 `daily`。
+   * 可选主题，用于决定默认 wiki page 路径。
    */
-  target?: MemorySourceType;
+  topic?: string;
+
   /**
-   * 目标会话 ID（`working` 目标必填）。
+   * 可选目标 wiki page 路径。
    */
-  sessionId?: string;
+  path?: string;
+
+  /**
+   * 可选来源说明。
+   */
+  source?: string;
 }
 
 /**
- * 显式写入响应。
+ * remember 响应。
  */
-export interface MemoryStoreResponse {
+export interface MemoryRememberResponse {
   /**
-   * 实际写入路径（相对项目根目录）。
+   * 原始 source 归档路径。
    */
-  path: string;
+  sourcePath: string;
+
   /**
-   * 实际写入目标层。
+   * 写入或更新的 wiki page 路径。
    */
-  target: MemorySourceType;
+  wikiPath: string;
+
   /**
-   * 写入字节长度（UTF-16 字符计数）。
+   * 当前写入策略。
+   */
+  mode: "appended" | "revised";
+
+  /**
+   * 写入内容字符数。
    */
   writtenChars: number;
+
+  /**
+   * 可选摘要。
+   */
+  summary?: string;
 }
 
 /**
- * Flush 请求。
+ * digest 请求。
  */
-export interface MemoryFlushPayload {
+export interface MemoryDigestPayload {
   /**
-   * 目标会话 ID。
+   * 目标 session id。
    */
   sessionId: string;
+
   /**
    * 可选最大提取消息条数。
    */
@@ -186,21 +381,78 @@ export interface MemoryFlushPayload {
 }
 
 /**
- * Flush 响应。
+ * digest 响应。
  */
-export interface MemoryFlushResponse {
+export interface MemoryDigestResponse {
   /**
-   * 写入路径（相对项目根目录）。
+   * 原始 session source 归档路径。
    */
-  path: string;
+  sourcePath: string;
+
+  /**
+   * 写入或更新的 wiki page 路径集合。
+   */
+  wikiPaths: string[];
+
   /**
-   * 参与 flush 的消息条数。
+   * 参与 digest 的消息条数。
    */
   messageCount: number;
+
+  /**
+   * 当前 digest 模式。
+   */
+  mode: "archived" | "digested";
+
+  /**
+   * 可选摘要。
+   */
+  summary?: string;
+}
+
+/**
+ * revise 请求。
+ */
+export interface MemoryRevisePayload {
+  /**
+   * 要修订的 wiki page 路径。
+   */
+  path: string;
+
+  /**
+   * 修订指令。
+   */
+  instruction: string;
+
+  /**
+   * 新证据或需要合入的内容。
+   */
+  evidence?: string;
+}
+
+/**
+ * revise 响应。
+ */
+export interface MemoryReviseResponse {
+  /**
+   * 实际写入的 wiki page 路径。
+   */
+  path: string;
+
+  /**
+   * 当前 revise 模式。
+   */
+  mode: "appended" | "revised";
+
   /**
    * 写入内容字符数。
    */
   writtenChars: number;
+
+  /**
+   * 可选摘要。
+   */
+  summary?: string;
 }
 
 /**
@@ -211,10 +463,12 @@ export interface MemorySourceStat {
    * 来源分类。
    */
   source: MemorySourceType;
+
   /**
    * 文件数量。
    */
   files: number;
+
   /**
    * 片段数量。
    */
@@ -229,18 +483,22 @@ export interface MemoryStatusResponse {
    * 后端标识。
    */
   backend: "builtin";
+
   /**
    * 当前检索模式。
    */
   mode: MemorySearchMode;
+
   /**
    * 文件总数。
    */
   files: number;
+
   /**
    * chunk 总数。
    */
   chunks: number;
+
   /**
    * 按来源统计。
    */
@@ -248,17 +506,19 @@ export interface MemoryStatusResponse {
 }
 
 /**
- * Memory service 内置默认配置（不暴露复杂用户配置）。
+ * Memory service 内置默认配置。
  */
 export interface MemoryDefaults {
   /**
    * 检索默认返回条数。
    */
   maxResults: number;
+
   /**
    * 检索默认最小分数。
    */
   minScore: number;
+
   /**
    * 注入预算（字符）。
    */
@@ -270,7 +530,8 @@ export interface MemoryDefaults {
  */
 export type MemoryActionPayload =
   | MemorySearchPayload
-  | MemoryGetPayload
-  | MemoryStorePayload
-  | MemoryFlushPayload
+  | MemoryReadPayload
+  | MemoryRememberPayload
+  | MemoryDigestPayload
+  | MemoryRevisePayload
   | Record<string, JsonValue>;

package/src/shell/ShellPlugin.ts

@@ -14,6 +14,7 @@ import type {
   ShellPluginState,
   ShellSessionRuntimeState,
 } from "@/shell/ShellRuntimeTypes.js";
+import type { ShellPluginOptions } from "@/shell/types/ShellPluginOptions.js";
 import type {
   ShellCloseRequest,
   ShellExecRequest,
@@ -60,9 +61,9 @@ export class ShellPlugin extends BasePlugin {
    */
   public readonly sessions: Map<string, ShellSessionRuntimeState>;
 
-  constructor() {
+  constructor(options: ShellPluginOptions = {}) {
     super();
-    this.state = createShellPluginState();
+    this.state = createShellPluginState(options);
     this.sessions = this.state.sessions;
     this.actions = {
       exec: {
@@ -121,7 +122,7 @@ export class ShellPlugin extends BasePlugin {
           }
         }
         this.state.sessions.clear();
-        this.state.boundRuntime = null;
+        this.state.context = null;
       },
     };
   }

package/src/shell/ShellRuntimeTypes.ts

@@ -10,6 +10,7 @@
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
 import type { ShellSessionSnapshot } from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+import type { ResolvedShellPluginOptions } from "@/shell/types/ShellPluginOptions.js";
 
 /**
  * 单个 shell wait 调用挂起时注册的 waiter。
@@ -79,16 +80,20 @@ export type ShellSessionRuntimeState = {
  * `ShellPlugin` 实例级状态。
  */
 export type ShellPluginState = {
+  /**
+   * 当前 shell plugin 归一化后的运行参数。
+   */
+  options: ResolvedShellPluginOptions;
   /**
    * 当前实例持有的全部 in-memory shell session。
    */
   sessions: Map<string, ShellSessionRuntimeState>;
   /**
-   * 当前实例最近一次绑定的 execution runtime。
+   * 当前实例最近一次启动时绑定的 agent context。
    *
    * 关键点（中文）
    * - 仅用于 shell 自动通知 chat 的回调路径。
    * - 这是实例字段，不再是模块级全局变量。
    */
-  boundRuntime: AgentContext | null;
+  context: AgentContext | null;
 };

package/src/shell/runtime/ShellActionRuntime.ts

@@ -31,12 +31,9 @@ import { getShellDir, getShellOutputPath, getShellSnapshotPath } from "./Paths.j
 import {
   buildActionResponse,
   buildShellEnv,
-  clampWaitMs,
+  clampWaitMsWithOptions,
   createOutputChunk,
   createShellPluginState,
-  DEFAULT_EXEC_TIMEOUT_MS,
-  DEFAULT_INLINE_WAIT_MS,
-  DEFAULT_WAIT_TIMEOUT_MS,
   ensureCapacity,
   isInMemorySession,
   isTerminalStatus,
@@ -65,7 +62,7 @@ export function bindShellRuntime(
   state: ShellPluginState,
   context: AgentContext,
 ): void {
-  state.boundRuntime = context;
+  state.context = context;
 }
 
 /**
@@ -189,7 +186,11 @@ export async function startShellSession(
   attachShellProcessEventHandlers({ state, session });
   await persistSnapshot(session);
 
-  const inlineWaitMs = clampWaitMs(request.inlineWaitMs, DEFAULT_INLINE_WAIT_MS);
+  const inlineWaitMs = clampWaitMsWithOptions(
+    state.options,
+    request.inlineWaitMs,
+    state.options.defaultInlineWaitMs,
+  );
   await waitShellSession(state, context, {
     shellId,
     afterVersion: 1,
@@ -351,7 +352,11 @@ export async function waitShellSession(
       };
       const timer = setTimeout(() => {
         finish();
-      }, clampWaitMs(request.timeoutMs, DEFAULT_WAIT_TIMEOUT_MS));
+      }, clampWaitMsWithOptions(
+        state.options,
+        request.timeoutMs,
+        state.options.defaultWaitTimeoutMs,
+      ));
       waiter = {
         resolve: finish,
         timer,
@@ -445,13 +450,17 @@ export async function execShellCommand(
   context: AgentContext,
   request: ShellExecRequest,
 ): Promise<ShellActionResponse> {
-  const timeoutMs = clampWaitMs(request.timeoutMs, DEFAULT_EXEC_TIMEOUT_MS);
+  const timeoutMs = clampWaitMsWithOptions(
+    state.options,
+    request.timeoutMs,
+    state.options.defaultExecTimeoutMs,
+  );
   const started = await startShellSession(state, context, {
     cmd: request.cmd,
     ...(request.cwd ? { cwd: request.cwd } : {}),
     ...(request.shell ? { shell: request.shell } : {}),
     login: request.login,
-    inlineWaitMs: Math.min(DEFAULT_INLINE_WAIT_MS, timeoutMs),
+    inlineWaitMs: Math.min(state.options.defaultInlineWaitMs, timeoutMs),
     maxOutputTokens: request.maxOutputTokens,
     autoNotifyOnExit: false,
   });