@ai-setting/roy-agent-core 1.0.0

package/src/env/mcp/types.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview MCP 类型定义
+ */
+
+import { z } from "zod";
+
+// ========== MCP Server 配置 ==========
+
+/**
+ * Local MCP Server 配置（stdio 传输）
+ */
+export const McpServerLocalConfigSchema = z.object({
+  type: z.literal("local"),
+  command: z.array(z.string()).min(1),
+  environment: z.record(z.string(), z.string()).optional(),
+  enabled: z.boolean().optional().default(true),
+  timeout: z.number().int().positive().optional(),
+});
+
+export type McpServerLocalConfig = z.infer<typeof McpServerLocalConfigSchema>;
+
+/**
+ * Remote MCP Server 配置（HTTP 传输）
+ */
+export const McpServerRemoteConfigSchema = z.object({
+  type: z.literal("remote"),
+  url: z.string().url(),
+  enabled: z.boolean().optional().default(true),
+  headers: z.record(z.string(), z.string()).optional(),
+  timeout: z.number().int().positive().optional(),
+});
+
+export type McpServerRemoteConfig = z.infer<typeof McpServerRemoteConfigSchema>;
+
+/**
+ * MCP Server 配置（联合类型）
+ */
+export const McpServerConfigSchema = z.discriminatedUnion("type", [
+  McpServerLocalConfigSchema,
+  McpServerRemoteConfigSchema,
+]);
+
+export type McpServerConfig = z.infer<typeof McpServerConfigSchema>;
+
+// ========== 扫描发现的服务器 ==========
+
+/**
+ * 扫描发现的 MCP 服务器信息
+ */
+export interface DiscoveredMcpServer {
+  /** 服务器名称（目录名） */
+  name: string;
+  /** 入口脚本路径 */
+  entryPath?: string;
+  /** 配置文件路径 */
+  configPath?: string;
+  /** package.json 路径 */
+  packagePath?: string;
+  /** 目录中的配置 */
+  directoryConfig?: Record<string, unknown>;
+  /** 解析后的默认命令（兼容不同路径） */
+  defaultCommand?: string[];
+}
+
+// ========== 服务器状态 ==========
+
+/**
+ * MCP 服务器状态
+ */
+export interface McpServerStatus {
+  /** 服务器名称 */
+  name: string;
+  /** 连接状态 */
+  status: "connecting" | "connected" | "disconnected" | "error";
+  /** 错误信息 */
+  error?: string;
+  /** 工具数量 */
+  toolsCount?: number;
+}

package/src/env/memory/README.md

@@ -0,0 +1,177 @@
+# MemoryComponent
+
+> 记忆管理核心组件
+
+## 概述
+
+MemoryComponent 是 roy-agent 的**记忆管理核心组件**，负责：
+- 管理本地文件系统记忆存储
+- 注册记忆操作工具（record_memory, recall_memory）
+- 支持 project/global 两种作用域
+
+## 快速开始
+
+### 1. 在 Environment 中注册
+
+```typescript
+import { BaseEnvironment } from "@roy-agent/core";
+import { MemoryComponent } from "@roy-agent/core";
+import { ToolComponent } from "@roy-agent/core";
+
+export class MyEnvironment extends BaseEnvironment {
+  protected registerDefaultComponents(): void {
+    // 注册 ToolComponent（MemoryComponent 依赖它）
+    if (!this.getComponent("tool")) {
+      this.registerComponent(new ToolComponent());
+    }
+
+    // 注册 MemoryComponent
+    const memoryComponent = new MemoryComponent();
+    this.registerComponent(memoryComponent);
+  }
+}
+```
+
+### 2. 初始化配置
+
+```typescript
+const memoryComponent = new MemoryComponent();
+await memoryComponent.init({
+  options: {
+    config: {
+      memoryPaths: [
+        { type: "global", path: "~/.config/roy-agent/memory" },
+        { type: "project", path: ".roy/memory" },
+      ],
+      recursive: true,
+      cacheEnabled: true,
+      cacheTTL: 5 * 60 * 1000, // 5 分钟
+    },
+  },
+});
+```
+
+### 3. 启动组件
+
+```typescript
+await memoryComponent.start();
+// MemoryComponent 会自动注册 2 个工具：
+// - record_memory
+// - recall_memory
+```
+
+## 工具 API
+
+### record_memory
+
+记录记忆到指定 scope 的 memory.md 文件。
+
+```typescript
+// 追加内容
+await memoryComponent.recordMemory({
+  scope: "project",
+  mode: "append",
+  content: "# 新记忆\n\n...",
+  title: "项目架构更新",
+});
+
+// 覆盖内容
+await memoryComponent.recordMemory({
+  scope: "global",
+  mode: "overwrite",
+  content: "# 全局记忆\n\n...",
+});
+
+// 删除记忆
+await memoryComponent.recordMemory({
+  scope: "project",
+  mode: "delete",
+});
+```
+
+**参数**:
+- `scope`: 作用域 - `"project"` 或 `"global"` (必填)
+- `mode`: 操作模式 - `"append"`, `"prepend"`, `"overwrite"`, `"delete"`
+- `content`: 记忆内容 (delete 模式不需要)
+- `title`: 章节标题 (可选)
+
+### recall_memory
+
+回忆记忆，从指定 scope 读取 memory.md 文件。
+
+```typescript
+// 读取所有 scope 的记忆
+const allMemory = await memoryComponent.recallMemory();
+
+// 只读取 project scope
+const projectMemory = await memoryComponent.recallMemory("project");
+
+// 只读取 global scope
+const globalMemory = await memoryComponent.recallMemory("global");
+```
+
+**参数**:
+- `scope`: 作用域 - `"project"` 或 `"global"` (可选，不传则读取所有)
+
+## 文件路径
+
+```
+~/.config/roy-agent/memory/
+└── memory.md              # global scope（全局记忆）
+
+.roy/memory/
+└── memory.md              # project scope（项目记忆，根据工作目录动态）
+```
+
+## CLI 使用
+
+```bash
+# 记录记忆（必填 --scope 参数）
+roy memory record --scope project --mode append --content "# 新内容" --title "标题"
+roy memory record --scope global --mode overwrite --content "# 全局内容"
+
+# 回忆记忆（可选 --scope 参数）
+roy memory recall                    # 读取所有 scope
+roy memory recall --scope project    # 只读取 project scope
+roy memory recall --scope global     # 只读取 global scope
+```
+
+## 配置
+
+### 默认配置
+
+```typescript
+{
+  memoryPaths: [
+    { type: "global", path: "~/.config/roy-agent/memory" },
+    { type: "project", path: ".roy/memory" },
+  ],
+  recursive: true,
+  cacheEnabled: true,
+  cacheTTL: 5 * 60 * 1000,
+  memoryFile: "memory.md",
+}
+```
+
+### 环境变量
+
+```bash
+# 设置 memory paths
+export MEMORY_MEMORYPATHS='[{"type":"global","path":"/home/user/.config/roy-agent/memory"},{"type":"project","path":".roy/memory"}]'
+
+# 设置递归扫描
+export MEMORY_RECURSIVE=true
+```
+
+## 类型定义
+
+```typescript
+import type {
+  MemoryConfig,
+  MemoryPath,
+  RecordMemoryMode,
+  RecordMemoryResult,
+  RecordMemoryParams,
+  RecallMemoryParams,
+} from "@roy-agent/core";
+```

package/src/env/memory/built-in/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Memory Built-in Tools Index
+ * 
+ * 简化的记忆工具导出
+ * 
+ * 只暴露两个工具：
+ * - record_memory: 统一的记忆写入工具
+ * - recall_memory: 统一的记忆读取工具
+ */
+
+import type { Tool } from "../../tool/types";
+import type { MemoryPath, RecordMemoryResult } from "../types";
+import { createRecordMemoryTool, RecordMemorySchema } from "./record-memory";
+import { createRecallMemoryTool, RecallMemorySchema } from "./recall-memory";
+
+/**
+ * record_memory 工具操作接口
+ */
+export interface RecordMemoryOperations {
+  (args: {
+    scope: "project" | "global";
+    mode: "append" | "prepend" | "overwrite" | "delete";
+    content?: string;
+    title?: string;
+  }): Promise<RecordMemoryResult | null>;
+}
+
+/**
+ * recall_memory 工具操作接口
+ */
+export interface RecallMemoryOperations {
+  (scope?: "project" | "global"): Promise<string>;
+}
+
+/**
+ * MemoryToolConfig
+ */
+export interface MemoryToolConfig {
+  getMemoryPaths: () => MemoryPath[];
+  getMemoryFile: () => string;
+}
+
+/**
+ * 创建所有记忆工具
+ */
+export function createMemoryTools(
+  recordMemory: RecordMemoryOperations,
+  recallMemory: RecallMemoryOperations,
+  config: MemoryToolConfig
+): Tool[] {
+  return [
+    createRecordMemoryTool(recordMemory, config.getMemoryPaths, config.getMemoryFile),
+    createRecallMemoryTool(recallMemory, config.getMemoryPaths, config.getMemoryFile),
+  ];
+}
+
+// Re-export schemas for external use
+export { RecordMemorySchema, type RecordMemoryParams } from "./record-memory";
+export { RecallMemorySchema, type RecallMemoryParams } from "./recall-memory";

package/src/env/memory/built-in/recall-memory.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview recall_memory Tool
+ * 
+ * 统一的记忆读取工具
+ */
+
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+import { z } from "zod";
+import type { MemoryPath } from "../types";
+
+/**
+ * recall_memory 工具参数
+ */
+export const RecallMemorySchema = z.object({
+  /** 作用域 (可选，不传则读取所有 scope) */
+  scope: z.enum(["project", "global"]).optional().describe("作用域（可选，不传则读取所有）"),
+});
+
+export type RecallMemoryParams = z.infer<typeof RecallMemorySchema>;
+
+export interface RecallMemoryOptions {
+  scope?: "project" | "global";
+}
+
+/**
+ * 创建 recall_memory 工具
+ */
+export function createRecallMemoryTool(
+  recallMemory: (scope?: "project" | "global") => Promise<string>,
+  getMemoryPaths: () => MemoryPath[],
+  getMemoryFile: () => string
+): Tool {
+  return {
+    name: "recall_memory",
+    description: buildDescription(getMemoryPaths, getMemoryFile),
+    parameters: RecallMemorySchema,
+    execute: async (args: unknown, _ctx: ToolContext): Promise<ToolResult> => {
+      const params = RecallMemorySchema.parse(args);
+      const startTime = Date.now();
+
+      try {
+        const content = await recallMemory(params.scope);
+
+        if (!content) {
+          return {
+            success: true,
+            output: "(No memory files found)",
+            metadata: { execution_time_ms: Date.now() - startTime },
+          };
+        }
+
+        return {
+          success: true,
+          output: content,
+          metadata: { execution_time_ms: Date.now() - startTime },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: "",
+          error: error instanceof Error ? error.message : String(error),
+          metadata: { execution_time_ms: Date.now() - startTime },
+        };
+      }
+    },
+  };
+}
+
+function buildDescription(
+  getMemoryPaths: () => MemoryPath[],
+  getMemoryFile: () => string
+): string {
+  const paths = getMemoryPaths();
+  const memoryFile = getMemoryFile();
+
+  const lines = [
+    `# Recall Memory Tool`,
+    "",
+    `Recall memory from memory files. Reads from the memory.md file in the specified scope.`,
+    "",
+    `## Parameters`,
+    "",
+    "- **scope** (optional): 作用域 - project 或 global（不传则读取所有）",
+    "",
+    `## Memory Files`,
+    "",
+  ];
+
+  if (paths.length === 0) {
+    lines.push("No memory paths configured.");
+  } else {
+    lines.push("Files will be read from:");
+    for (const p of paths) {
+      lines.push(`- **[${p.type}]** ${p.path}/${memoryFile}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// Re-export for external use
+export { RecallMemorySchema as UnifiedRecallMemorySchema };
+export type { RecallMemoryParams as UnifiedRecallMemoryParams };

package/src/env/memory/built-in/record-memory.ts

@@ -0,0 +1,148 @@
+// packages/core/src/env/memory/built-in/record-memory.ts
+
+/**
+ * @fileoverview record_memory Tool
+ * 
+ * 统一的记忆记录工具
+ */
+
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+import { z } from "zod";
+import type { MemoryPath, RecordMemoryResult } from "../types";
+
+/**
+ * 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>;
+
+export interface RecordMemoryOptions {
+  scope: "project" | "global";
+  mode: "append" | "prepend" | "overwrite" | "delete";
+  content?: string;
+  title?: string;
+}
+
+/**
+ * 创建 record_memory 工具
+ */
+export function createRecordMemoryTool(
+  recordMemory: (args: RecordMemoryOptions) => Promise<RecordMemoryResult | null>,
+  getMemoryPaths: () => MemoryPath[],
+  getMemoryFile: () => string
+): Tool {
+  return {
+    name: "record_memory",
+    description: buildDescription(getMemoryPaths, getMemoryFile),
+    parameters: RecordMemorySchema,
+    execute: async (args: unknown, _ctx: ToolContext): Promise<ToolResult> => {
+      const params = RecordMemorySchema.parse(args);
+      const startTime = Date.now();
+
+      try {
+        const result = await recordMemory({
+          scope: params.scope,
+          mode: params.mode,
+          content: params.content,
+          title: params.title,
+        });
+
+        if (!result) {
+          return {
+            success: false,
+            output: "",
+            error: "未配置 memory 路径，无法记录记忆",
+            metadata: { execution_time_ms: Date.now() - startTime },
+          };
+        }
+
+        const actionMessages: Record<string, string> = {
+          created: "已创建记忆文件",
+          overwrite: "已覆盖记忆文件",
+          append: "已追加内容到记忆文件",
+          prepend: "已插入内容到记忆文件开头",
+          delete: "已删除记忆文件",
+        };
+
+        return {
+          success: true,
+          output: `${actionMessages[result.action]}: ${result.path}`,
+          metadata: {
+            execution_time_ms: Date.now() - startTime,
+            path: result.path,
+            action: result.action,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: "",
+          error: error instanceof Error ? error.message : String(error),
+          metadata: { execution_time_ms: Date.now() - startTime },
+        };
+      }
+    },
+  };
+}
+
+function buildDescription(
+  getMemoryPaths: () => MemoryPath[],
+  getMemoryFile: () => string
+): string {
+  const paths = getMemoryPaths();
+  const memoryFile = getMemoryFile();
+
+  const lines = [
+    `# Record Memory Tool`,
+    "",
+    `Record memory to file. Writes to the memory.md file in the specified scope.`,
+    "",
+    `## Modes`,
+    "",
+    "| Mode | Description |",
+    "|------|-------------|",
+    "| **append** | 追加内容到 ${memoryFile} 尾部 |",
+    "| **prepend** | 插入内容到 ${memoryFile} 开头 |",
+    "| **overwrite** | 覆盖 ${memoryFile} |",
+    "| **delete** | 删除 ${memoryFile} |",
+    "",
+    `## Parameters`,
+    "",
+    "- **scope** (required): 作用域 - project 或 global",
+    "- **mode** (required): 操作模式",
+    "- **content** (optional): 记忆内容",
+    "- **title** (optional): 章节标题",
+    "",
+    `## Memory Paths`,
+    "",
+  ];
+
+  if (paths.length === 0) {
+    lines.push("No memory paths configured.");
+  } else {
+    lines.push("Files will be written to:");
+    for (const p of paths) {
+      lines.push(`- **[${p.type}]** ${p.path}/${memoryFile}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// Re-export for external use
+export { RecordMemorySchema as UnifiedRecordMemorySchema };
+export type { RecordMemoryParams as UnifiedRecordMemoryParams };

package/src/env/memory/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Memory Component Index
+ * 
+ * 导出 Memory 组件及相关类型
+ */
+
+// Types - only export from one place to avoid duplicates
+export * from "./types";
+
+// Config
+export { DEFAULT_MEMORY_CONFIG, SOURCE_PRIORITY, getSourcePriority } from "./memory-config";
+
+// Component
+export { MemoryComponent, type MemoryComponentOptions } from "./memory-component";
+
+// Built-in Tools - export only schemas to avoid type conflicts
+export { RecordMemorySchema, RecallMemorySchema } from "./built-in";
+
+// Memory Plugin (for --plugin memory)
+export * from "./plugin";