@ai-setting/roy-agent-core 1.0.0

package/src/env/memory/tools/memory-agent-tools.ts

@@ -0,0 +1,228 @@
+/**
+ * @fileoverview Memory Agent Tools
+ * 
+ * Memory Agent 使用的工具：
+ * - search_sessions: 搜索会话历史
+ * - get_session: 获取指定会话
+ * - write_memory: 写入记忆文件
+ * - bash: 执行 Shell 命令（用于探索项目结构）
+ * - read_file: 读取文件内容（用于阅读文档）
+ */
+
+import { z } from "zod";
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+import { readFileTool, bashTool } from "../../tool/built-in";
+
+// ============================================================================
+// Tool Input Schemas
+// ============================================================================
+
+/**
+ * search_sessions 输入参数
+ */
+export const SearchSessionsSchema = z.object({
+  query: z.string().describe("搜索关键词"),
+  session_id: z.string().optional().describe("可选：限制特定 session"),
+  limit: z.number().optional().default(10).describe("返回数量限制"),
+});
+
+export type SearchSessionsParams = z.infer<typeof SearchSessionsSchema>;
+
+/**
+ * get_session 输入参数
+ */
+export const GetSessionSchema = z.object({
+  session_id: z.string().describe("Session ID"),
+});
+
+export type GetSessionParams = z.infer<typeof GetSessionSchema>;
+
+/**
+ * write_memory 输入参数
+ */
+export const WriteMemorySchema = z.object({
+  scope: z.enum(["project", "global"]).describe("作用域"),
+  content: z.string().describe("新的记忆内容（Markdown 格式）"),
+});
+
+export type WriteMemoryParams = z.infer<typeof WriteMemorySchema>;
+
+// ============================================================================
+// Component Interfaces
+// ============================================================================
+
+/**
+ * Session Component 接口（需要 searchSessions, getSession 方法）
+ */
+export interface MemoryAgentSessionComponent {
+  /**
+   * 列出所有会话（用于 search_sessions）
+   */
+  list(options?: any): Promise<any[]>;
+  /**
+   * 获取会话上下文（包含消息）
+   */
+  getContext(sessionId: string, options?: any): Promise<any>;
+  /**
+   * 搜索会话（通过 grep 命令）
+   */
+  searchSessions(query: string, options?: { session_id?: string; limit?: number }): Promise<any[]>;
+  /**
+   * 获取单个会话
+   */
+  getSession(sessionId: string): Promise<any | null>;
+}
+
+/**
+ * Memory Component 接口（需要 recallMemory, recordMemory 方法）
+ */
+export interface MemoryAgentMemoryComponent {
+  recallMemory(scope?: "project" | "global"): Promise<string | null>;
+  recordMemory(params: { mode: string; content: string; scope?: string }): Promise<void>;
+}
+
+/**
+ * Config Component 接口
+ */
+export interface MemoryAgentConfigComponent {
+  get(key: string): unknown;
+}
+
+// ============================================================================
+// Tool Factory
+// ============================================================================
+
+/**
+ * Memory Agent 工具工厂
+ */
+export function createMemoryAgentTools(deps: {
+  sessionComponent: MemoryAgentSessionComponent;
+  memoryComponent: MemoryAgentMemoryComponent;
+  configComponent?: MemoryAgentConfigComponent;
+}): {
+  searchSessions: Tool;
+  getSession: Tool;
+  writeMemory: Tool;
+  bash: Tool;
+  read_file: Tool;
+} {
+  // ============================================================================
+  // search_sessions tool
+  // ============================================================================
+  const searchSessions: Tool = {
+    name: "search_sessions",
+    description: "搜索会话历史，返回匹配的会话摘要列表",
+    parameters: SearchSessionsSchema as unknown as Tool["parameters"],
+    execute: async (args: unknown, ctx: ToolContext): Promise<ToolResult> => {
+      try {
+        const params = SearchSessionsSchema.parse(args);
+
+        const results = await deps.sessionComponent.searchSessions(params.query, {
+          session_id: params.session_id,
+          limit: params.limit,
+        });
+
+        return {
+          success: true,
+          output: JSON.stringify(results, null, 2),
+          metadata: {
+            execution_time_ms: 0,
+            count: results.length,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: "",
+          error: error instanceof Error ? error.message : String(error),
+          metadata: { execution_time_ms: 0 },
+        };
+      }
+    },
+  };
+
+  // ============================================================================
+  // get_session tool
+  // ============================================================================
+  const getSession: Tool = {
+    name: "get_session",
+    description: "获取指定会话的完整内容",
+    parameters: GetSessionSchema as unknown as Tool["parameters"],
+    execute: async (args: unknown, ctx: ToolContext): Promise<ToolResult> => {
+      try {
+        const params = GetSessionSchema.parse(args);
+
+        const session = await deps.sessionComponent.getSession(params.session_id);
+
+        if (!session) {
+          return {
+            success: false,
+            output: "",
+            error: `Session not found: ${params.session_id}`,
+            metadata: { execution_time_ms: 0 },
+          };
+        }
+
+        return {
+          success: true,
+          output: JSON.stringify(session, null, 2),
+          metadata: {
+            execution_time_ms: 0,
+            session_id: session.sessionId,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: "",
+          error: error instanceof Error ? error.message : String(error),
+          metadata: { execution_time_ms: 0 },
+        };
+      }
+    },
+  };
+
+  // ============================================================================
+  // write_memory tool
+  // ============================================================================
+  const writeMemory: Tool = {
+    name: "write_memory",
+    description: "写入记忆文件（覆盖模式）",
+    parameters: WriteMemorySchema as unknown as Tool["parameters"],
+    execute: async (args: unknown, ctx: ToolContext): Promise<ToolResult> => {
+      try {
+        const params = WriteMemorySchema.parse(args);
+
+        await deps.memoryComponent.recordMemory({
+          mode: "overwrite",
+          content: params.content,
+          scope: params.scope,
+        });
+
+        return {
+          success: true,
+          output: `Memory updated successfully (${params.scope})`,
+          metadata: {
+            execution_time_ms: 0,
+            scope: params.scope,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: "",
+          error: error instanceof Error ? error.message : String(error),
+          metadata: { execution_time_ms: 0 },
+        };
+      }
+    },
+  };
+
+  return {
+    searchSessions,
+    getSession,
+    writeMemory,
+    bash: bashTool,
+    read_file: readFileTool,
+  };
+}

package/src/env/memory/types.ts

@@ -0,0 +1,85 @@
+// packages/core/src/env/memory/types.ts
+
+import { z } from "zod";
+
+// ==================== 基础类型 ====================
+
+/**
+ * Memory 来源类型
+ * - project: 项目级记忆
+ * - global: 全局记忆
+ */
+export type MemorySource = "project" | "global";
+
+/**
+ * Memory 路径配置
+ */
+export interface MemoryPath {
+  /** 来源类型 */
+  type: MemorySource;
+  /** 绝对路径 */
+  path: string;
+}
+
+/**
+ * MemoryComponent 配置
+ */
+export interface MemoryConfig {
+  /** 多路径配置 */
+  memoryPaths: MemoryPath[];
+  /** 是否递归扫描子目录 */
+  recursive: boolean;
+  /** 是否启用缓存 */
+  cacheEnabled: boolean;
+  /** 缓存有效期（毫秒） */
+  cacheTTL?: number;
+  /** 记忆文件名 */
+  memoryFile?: string;
+}
+
+/**
+ * record_memory 操作模式
+ */
+export type RecordMemoryMode = "append" | "prepend" | "overwrite" | "delete";
+
+/**
+ * record_memory 操作结果
+ */
+export interface RecordMemoryResult {
+  /** 文件路径 */
+  path: string;
+  /** 操作类型 */
+  action: "created" | "append" | "prepend" | "overwrite" | "delete";
+}
+
+// ==================== Tool 参数 Schema ====================
+
+/**
+ * record_memory 工具参数
+ */
+export const RecordMemorySchema = z.object({
+  /** 作用域 (必填) */
+  scope: z.enum(["project", "global"]).describe("作用域: project/global"),
+  
+  /** 操作模式 */
+  mode: z.enum(["append", "prepend", "overwrite", "delete"])
+    .describe("模式: append(追加)/prepend(插入)/overwrite(覆盖)/delete(删除)"),
+  
+  /** 记忆内容 (delete 模式不需要) */
+  content: z.string().optional().describe("记忆内容"),
+  
+  /** 章节标题 (可选，用于生成 ## title 章节) */
+  title: z.string().optional().describe("章节标题"),
+});
+
+export type RecordMemoryParams = z.infer<typeof RecordMemorySchema>;
+
+/**
+ * recall_memory 工具参数
+ */
+export const RecallMemorySchema = z.object({
+  /** 作用域 (可选，不传则读取所有 scope) */
+  scope: z.enum(["project", "global"]).optional().describe("作用域（可选，不传则读取所有）"),
+});
+
+export type RecallMemoryParams = z.infer<typeof RecallMemorySchema>;

package/src/env/paths.ts

@@ -0,0 +1,118 @@
+import os from "os";
+import path from "path";
+
+/**
+ * APP 名称
+ */
+const APP_NAME = "roy-agent";
+
+/**
+ * XDG 基础目录类型
+ */
+export type XDGDirType = "config" | "state" | "data" | "cache";
+
+/**
+ * XDG 路径接口
+ */
+export interface XDGPaths {
+  home: string;
+  config: string;
+  state: string;
+  data: string;
+  cache: string;
+}
+
+/**
+ * 获取 XDG 基础路径
+ */
+function getXdgBase(): { config: string; state: string; data: string; cache: string } {
+  const home = os.homedir();
+
+  // 尝试使用 xdg-basedir，失败则使用默认路径
+  try {
+    const xdg = require("xdg-basedir");
+    return {
+      config: xdg.xdgConfig || path.join(home, ".config"),
+      state: xdg.xdgState || path.join(home, ".local", "state"),
+      data: xdg.xdgData || path.join(home, ".local", "share"),
+      cache: xdg.xdgCache || path.join(home, ".cache"),
+    };
+  } catch {
+    return {
+      config: path.join(home, ".config"),
+      state: path.join(home, ".local", "state"),
+      data: path.join(home, ".local", "share"),
+      cache: path.join(home, ".cache"),
+    };
+  }
+}
+
+/**
+ * 计算 XDG 路径
+ */
+function computeXDGPaths(): XDGPaths {
+  const home = os.homedir();
+  const xdg = getXdgBase();
+
+  return {
+    home,
+    config: path.join(xdg.config, APP_NAME),
+    state: path.join(xdg.state, APP_NAME),
+    data: path.join(xdg.data, APP_NAME),
+    cache: path.join(xdg.cache, APP_NAME),
+  };
+}
+
+/**
+ * XDG 路径计算器（惰性计算）
+ */
+class XDGPathsCalculator {
+  private _paths?: XDGPaths;
+
+  get paths(): XDGPaths {
+    if (!this._paths) {
+      this._paths = computeXDGPaths();
+    }
+    return this._paths;
+  }
+
+  /**
+   * 获取特定类型的路径
+   */
+  getPath(type: XDGDirType): string {
+    return this.paths[type];
+  }
+
+  /**
+   * 计算 Component 的绝对路径
+   */
+  getComponentPath(base: XDGDirType, subPath: string): string {
+    return path.join(this.paths[base], subPath);
+  }
+
+  /**
+   * 强制重新计算路径（用于测试或配置变更）
+   */
+  reset(): void {
+    this._paths = undefined;
+  }
+}
+
+/**
+ * 全局 XDG 路径实例
+ */
+export const XDG_PATHS = new XDGPathsCalculator();
+
+/**
+ * 获取 XDG 路径
+ */
+export function getXDGPaths(): XDGPaths {
+  return XDG_PATHS.paths;
+}
+
+/**
+ * 获取特定类型的 XDG 路径
+ */
+export function getXDGPath(type: XDGDirType): string {
+  return XDG_PATHS.getPath(type);
+}

package/src/env/prompt/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview PromptComponent 导出
+ */
+
+export { PromptComponent, type PromptComponentOptions } from "./prompt-component";
+export { PromptRenderer } from "./renderer";
+
+export type {
+  PromptConfig,
+  PromptPath,
+  PromptEntry,
+  PromptSource,
+  PromptHook,
+  RenderHookContext,
+  PromptHookMap,
+} from "./types";
+
+export { PromptConfigSchema, PromptPathSchema } from "./types";

package/src/env/prompt/memory-prompts.test.ts

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Memory Agent Prompts Tests
+ * 
+ * TDD 测试：Memory Agent prompts
+ */
+
+import { describe, expect, test } from "vitest";
+import { builtInPrompts, getBuiltInPrompt, getBuiltInPromptNames } from "./prompts-index";
+
+describe("builtInPrompts", () => {
+  describe("should have project-memory prompt", () => {
+    test("project-memory prompt exists", () => {
+      expect(builtInPrompts["project-memory"]).toBeDefined();
+    });
+
+    test("project-memory prompt contains role", () => {
+      const prompt = builtInPrompts["project-memory"];
+      expect(prompt).toContain("项目记忆管理专家");
+    });
+
+    test("project-memory prompt contains tools reference", () => {
+      const prompt = builtInPrompts["project-memory"];
+      expect(prompt).toContain("search_sessions");
+      expect(prompt).toContain("get_session");
+      expect(prompt).toContain("record_memory");
+    });
+
+    test("project-memory prompt contains variable placeholder", () => {
+      const prompt = builtInPrompts["project-memory"];
+      expect(prompt).toContain("{CURRENT_MEMORY}");
+      expect(prompt).toContain("{USER_REQUIREMENT}");
+      expect(prompt).toContain("{SCOPE}");
+    });
+  });
+
+  describe("should have global-memory prompt", () => {
+    test("global-memory prompt exists", () => {
+      expect(builtInPrompts["global-memory"]).toBeDefined();
+    });
+
+    test("global-memory prompt contains role", () => {
+      const prompt = builtInPrompts["global-memory"];
+      expect(prompt).toContain("全局记忆管理专家");
+    });
+
+    test("global-memory prompt contains tools reference", () => {
+      const prompt = builtInPrompts["global-memory"];
+      expect(prompt).toContain("search_sessions");
+      expect(prompt).toContain("get_session");
+      expect(prompt).toContain("record_memory");
+    });
+
+    test("global-memory prompt contains variable placeholder", () => {
+      const prompt = builtInPrompts["global-memory"];
+      expect(prompt).toContain("{CURRENT_MEMORY}");
+      expect(prompt).toContain("{USER_REQUIREMENT}");
+      expect(prompt).toContain("{SCOPE}");
+    });
+  });
+});
+
+describe("getBuiltInPrompt", () => {
+  test("should return project-memory prompt", () => {
+    const prompt = getBuiltInPrompt("project-memory");
+    expect(prompt).toBeDefined();
+    expect(prompt).toContain("项目记忆管理专家");
+  });
+
+  test("should return global-memory prompt", () => {
+    const prompt = getBuiltInPrompt("global-memory");
+    expect(prompt).toBeDefined();
+    expect(prompt).toContain("全局记忆管理专家");
+  });
+
+  test("should return undefined for unknown prompt", () => {
+    const prompt = getBuiltInPrompt("unknown-prompt");
+    expect(prompt).toBeUndefined();
+  });
+});
+
+describe("getBuiltInPromptNames", () => {
+  test("should include project-memory", () => {
+    const names = getBuiltInPromptNames();
+    expect(names).toContain("project-memory");
+  });
+
+  test("should include global-memory", () => {
+    const names = getBuiltInPromptNames();
+    expect(names).toContain("global-memory");
+  });
+});