@ai-setting/roy-agent-core 1.0.0

package/src/env/log-trace/trace-context.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview Trace Context 实现
+ * 
+ * 基于 AsyncLocalStorage 的轻量级追踪上下文实现
+ */
+
+import { AsyncLocalStorage } from "async_hooks";
+import { type SpanContext, type ITraceContext, type TraceContextOptions } from "./types";
+
+interface RequestContextData {
+  requestId: string;
+  sessionId?: string;
+  timestamp: number;
+  spanContext?: SpanContext;
+}
+
+const contextStore = new AsyncLocalStorage<RequestContextData>();
+export { contextStore };
+
+/**
+ * 创建轻量级 TraceContext 实现
+ */
+function createLightweightContext(): ITraceContext {
+  return new LightweightTraceContext();
+}
+
+/**
+ * 轻量级 TraceContext 实现
+ */
+class LightweightTraceContext implements ITraceContext {
+  getRequestId(): string | undefined {
+    return contextStore.getStore()?.requestId;
+  }
+
+  getSpanContext(): SpanContext | undefined {
+    return contextStore.getStore()?.spanContext;
+  }
+
+  setSpanContext(spanContext: SpanContext): void {
+    const store = contextStore.getStore();
+    if (store) {
+      store.spanContext = spanContext;
+    }
+  }
+
+  runWithContext<T>(fn: () => T): T {
+    const store = contextStore.getStore();
+    if (store) {
+      return contextStore.run(store, fn);
+    }
+    return fn();
+  }
+
+  runWithNewContext<T>(requestId: string, sessionId: string | undefined, fn: () => T): T {
+    const context: RequestContextData = {
+      requestId,
+      sessionId,
+      timestamp: Date.now(),
+      spanContext: {
+        traceId: requestId,
+        spanId: this.generateSpanId(),
+      },
+    };
+    return contextStore.run(context, fn);
+  }
+
+  async runWithContextAsync<T>(fn: () => Promise<T>): Promise<T> {
+    const store = contextStore.getStore();
+    if (store) {
+      return contextStore.run(store, fn);
+    }
+    return fn();
+  }
+
+  async runWithNewContextAsync<T>(requestId: string, sessionId: string | undefined, fn: () => Promise<T>): Promise<T> {
+    const context: RequestContextData = {
+      requestId,
+      sessionId,
+      timestamp: Date.now(),
+      spanContext: {
+        traceId: requestId,
+        spanId: this.generateSpanId(),
+      },
+    };
+    return contextStore.run(context, fn);
+  }
+
+  generateRequestId(): string {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+  }
+
+  private generateSpanId(): string {
+    return `span_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+  }
+
+  initContext(requestId: string, sessionId?: string): void {
+    const context: RequestContextData = {
+      requestId,
+      sessionId,
+      timestamp: Date.now(),
+      spanContext: {
+        traceId: requestId,
+        spanId: this.generateSpanId(),
+      },
+    };
+    contextStore.enterWith(context);
+  }
+
+  startNewContext(requestId: string, sessionId?: string): () => void {
+    const context: RequestContextData = {
+      requestId,
+      sessionId,
+      timestamp: Date.now(),
+      spanContext: {
+        traceId: requestId,
+        spanId: this.generateSpanId(),
+      },
+    };
+    const previousStore = contextStore.getStore();
+    contextStore.enterWith(context);
+    
+    // 清理函数：恢复之前的上下文
+    // 注意：如果之前没有上下文，清理后 getStore() 会返回 undefined
+    return () => {
+      contextStore.enterWith(previousStore!);
+    };
+  }
+}
+
+// ============================================================================
+// 全局单例
+// ============================================================================
+
+let traceContextImpl: ITraceContext | null = null;
+
+/**
+ * 获取当前 TraceContext 实例
+ */
+export function getTraceContext(): ITraceContext {
+  if (!traceContextImpl) {
+    traceContextImpl = createLightweightContext();
+  }
+  return traceContextImpl;
+}
+
+/**
+ * 设置 TraceContext 实现（用于测试或替换）
+ */
+export function setTraceContext(impl: ITraceContext): void {
+  traceContextImpl = impl;
+}
+
+/**
+ * 初始化 TraceContext
+ */
+export function initTraceContext(options?: TraceContextOptions): ITraceContext {
+  // 目前只支持轻量级实现
+  traceContextImpl = createLightweightContext();
+  return traceContextImpl;
+}
+
+export type { ITraceContext, TraceContextOptions } from "./types";

package/src/env/log-trace/types.test.ts

@@ -0,0 +1,63 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import {
+  type SpanContext,
+  type SpanAttributes,
+  type Span,
+  SpanKind,
+  SpanStatus,
+} from "./types";
+
+describe("Types", () => {
+  describe("SpanContext", () => {
+    test("should have required fields", () => {
+      const context: SpanContext = {
+        traceId: "trace-123",
+        spanId: "span-456",
+      };
+      expect(context.traceId).toBe("trace-123");
+      expect(context.spanId).toBe("span-456");
+    });
+
+    test("should allow optional parentSpanId", () => {
+      const context: SpanContext = {
+        traceId: "trace-123",
+        spanId: "span-456",
+        parentSpanId: "span-789",
+      };
+      expect(context.parentSpanId).toBe("span-789");
+    });
+  });
+
+  describe("Span", () => {
+    test("should create a complete span", () => {
+      const span: Span = {
+        traceId: "trace-123",
+        spanId: "span-456",
+        name: "test-span",
+        kind: SpanKind.INTERNAL,
+        status: SpanStatus.OK,
+        startTime: Date.now(),
+        attributes: { "key": "value" },
+        children: [],
+      };
+      expect(span.name).toBe("test-span");
+      expect(span.kind).toBe(SpanKind.INTERNAL);
+      expect(span.status).toBe(SpanStatus.OK);
+    });
+  });
+
+  describe("SpanKind", () => {
+    test("should have correct values", () => {
+      expect(SpanKind.CLIENT).toBe("client");
+      expect(SpanKind.SERVER).toBe("server");
+      expect(SpanKind.INTERNAL).toBe("internal");
+    });
+  });
+
+  describe("SpanStatus", () => {
+    test("should have correct values", () => {
+      expect(SpanStatus.OK).toBe("ok");
+      expect(SpanStatus.ERROR).toBe("error");
+    });
+  });
+});

package/src/env/log-trace/types.ts

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Log & Trace Component 类型定义
+ */
+
+// ============================================================================
+// Span Types
+// ============================================================================
+
+/**
+ * Span 上下文
+ */
+export interface SpanContext {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+}
+
+/**
+ * Span 属性
+ */
+export interface SpanAttributes {
+  [key: string]: string | number | boolean | undefined | Record<string, unknown>;
+}
+
+/**
+ * Span
+ */
+export interface Span {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+
+  name: string;
+  kind: SpanKind;
+  status: SpanStatus;
+
+  startTime: number;
+  endTime?: number;
+
+  attributes: SpanAttributes;
+  result?: unknown;
+  error?: string;
+
+  children?: Span[];
+}
+
+/**
+ * Span 类型
+ */
+export enum SpanKind {
+  CLIENT = "client",
+  SERVER = "server",
+  INTERNAL = "internal",
+}
+
+/**
+ * Span 状态
+ */
+export enum SpanStatus {
+  OK = "ok",
+  ERROR = "error",
+}
+
+// ============================================================================
+// Trace Info Types
+// ============================================================================
+
+/**
+ * Trace 信息
+ */
+export interface TraceInfo {
+  traceId: string;
+  rootSpanName: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  spanCount: number;
+  status: "ok" | "error" | "mixed";
+}
+
+// ============================================================================
+// SpanStorage Types
+// ============================================================================
+
+/**
+ * SpanStorage 接口
+ */
+export interface SpanStorage {
+  initialize(): Promise<void>;
+  save(span: Span): void;
+  saveBatch(spans: Span[]): void;
+  findByTraceId(traceId: string): Span[];
+  findBySpanId(spanId: string): Span | undefined;
+  listTraces(limit?: number): TraceInfo[];
+  deleteByTraceId(traceId: string): void;
+  close(): void;
+}
+
+// ============================================================================
+// TraceContext Types
+// ============================================================================
+
+/**
+ * TraceContext 选项
+ */
+export interface TraceContextOptions {
+  /** 追踪器实现类型 */
+  impl?: "lightweight" | "opentelemetry";
+}
+
+/**
+ * ITraceContext 接口
+ */
+export interface ITraceContext {
+  /** 获取当前请求的 requestId */
+  getRequestId(): string | undefined;
+  
+  /** 获取当前 Span 上下文 */
+  getSpanContext(): SpanContext | undefined;
+  
+  /** 更新当前 Span 上下文（用于设置子 span 的 parentSpanId） */
+  setSpanContext(spanContext: SpanContext): void;
+  
+  /** 在已存在的追踪上下文中执行函数 */
+  runWithContext<T>(fn: () => T): T;
+  
+  /** 在新追踪上下文中执行函数（同步） */
+  runWithNewContext<T>(requestId: string, sessionId: string | undefined, fn: () => T): T;
+  
+  /** 在已存在的追踪上下文中执行异步函数 */
+  runWithContextAsync<T>(fn: () => Promise<T>): Promise<T>;
+  
+  /** 在新追踪上下文中执行函数（异步） */
+  runWithNewContextAsync<T>(requestId: string, sessionId: string | undefined, fn: () => Promise<T>): Promise<T>;
+  
+  /** 生成新的 requestId */
+  generateRequestId(): string;
+  
+  /** 初始化追踪上下文（请求入口调用） */
+  initContext(requestId: string, sessionId?: string): void;
+
+  /** 创建并进入新的追踪上下文（请求入口使用，返回清理函数） */
+  startNewContext(requestId: string, sessionId?: string): () => void;
+}
+
+// ============================================================================
+// Logger Types
+// ============================================================================
+
+/**
+ * 日志级别
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/**
+ * Logger 配置
+ */
+export interface LoggerConfig {
+  level?: LogLevel;
+  prefix?: string;
+  filename?: string;
+}
+
+/**
+ * Logger 接口
+ */
+export interface ILogger {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}

package/src/env/mcp/README.md

@@ -0,0 +1,244 @@
+# MCP Component 集成指南
+
+## 概述
+
+McpComponent 是 roy-agent 的 MCP 客户端管理组件，支持：
+- 本地 MCP 服务器（stdio 传输）
+- 远程 MCP 服务器（HTTP 传输）
+- 多路径扫描（类似 SkillComponent）
+- 与 ToolComponent 无缝集成
+
+## 快速开始
+
+### 1. 导入 McpComponent
+
+```typescript
+import { McpComponent } from "./mcp";
+```
+
+### 2. 注册到 Environment
+
+在具体的 Environment 子类中覆盖 `registerDefaultComponents()` 方法：
+
+```typescript
+import { McpComponent } from "./mcp";
+import type { ConfigComponent } from "../../config/config-component";
+
+export class MyEnvironment extends BaseEnvironment {
+  protected registerDefaultComponents(): void {
+    // 注册 ConfigComponent（如果尚未注册）
+    const configComponent = this.getComponent<ConfigComponent>("config");
+    if (!configComponent) {
+      this.registerComponent(new ConfigComponent());
+    }
+
+    // 注册 ToolComponent（如果尚未注册）
+    const toolComponent = this.getComponent<ToolComponent>("tool");
+    if (!toolComponent) {
+      this.registerComponent(new ToolComponent());
+    }
+
+    // 注册 McpComponent
+    const mcpComponent = new McpComponent();
+    this.registerComponent(mcpComponent);
+  }
+}
+```
+
+### 3. 配置 McpComponent
+
+通过 ConfigComponent 配置：
+
+```typescript
+// 在初始化时传入配置
+mcpComponent.init({
+  options: {
+    configComponent: myConfigComponent,
+    config: {
+      enabled: true,
+      mcpPaths: [
+        { type: "user", path: "~/.config/roy-agent/mcp" },
+        { type: "project", path: ".roy/mcp" },
+      ],
+      timeout: 30000,
+    },
+  },
+});
+```
+
+### 4. 启动顺序
+
+组件启动顺序很重要：
+
+```typescript
+async start(): Promise<void> {
+  await super.start();
+  
+  // 1. 先启动 ToolComponent
+  const toolComponent = this.getComponent<ToolComponent>("tool");
+  await toolComponent?.start();
+  
+  // 2. 再启动 McpComponent（McpComponent 需要 ToolComponent 来注册 tools）
+  const mcpComponent = this.getComponent<McpComponent>("mcp");
+  await mcpComponent?.start();
+}
+```
+
+## 配置方式
+
+### 方式 1: 代码配置
+
+```typescript
+mcpComponent.init({
+  options: {
+    configComponent,
+    config: {
+      mcpPaths: [
+        { type: "user", path: "~/.config/roy-agent/mcp" },
+      ],
+      servers: {
+        "my-server": {
+          type: "local",
+          command: ["bun", "run", "/path/to/server.ts"],
+        },
+      },
+    },
+  },
+});
+```
+
+### 方式 2: 环境变量
+
+```bash
+export MCP_ENABLED=true
+export MCP_TIMEOUT=60000
+```
+
+### 方式 3: 配置文件
+
+在配置文件中添加：
+
+```json
+{
+  "mcp": {
+    "enabled": true,
+    "timeout": 30000,
+    "mcpPaths": [
+      { "type": "user", "path": "~/.config/roy-agent/mcp" }
+    ]
+  }
+}
+```
+
+## MCP 服务器发现
+
+McpComponent 会扫描配置的路径，查找子目录作为 MCP 服务器：
+
+```
+~/.config/roy-agent/mcp/
+├── filesystem-mcp/
+│   ├── server.ts
+│   └── config.jsonc
+├── memory-mcp/
+│   └── server.mjs
+```
+
+### config.jsonc 格式
+
+```jsonc
+{
+  "enabled": true,
+  "command": ["bun", "run", "server.ts"],
+  "timeout": 60000,
+  "environment": {
+    "NODE_ENV": "production"
+  }
+}
+```
+
+## 远程 MCP 服务器
+
+可以通过显式配置添加远程 MCP 服务器：
+
+```typescript
+mcpComponent.init({
+  options: {
+    configComponent,
+    config: {
+      servers: {
+        "remote-api": {
+          type: "remote",
+          url: "https://mcp.example.com",
+          headers: {
+            "Authorization": "Bearer token"
+          }
+        }
+      }
+    }
+  }
+});
+```
+
+## 公共 API
+
+### 获取服务器状态
+
+```typescript
+const status = mcpComponent.getServerStatus("my-server");
+console.log(status?.status); // "connected" | "error" | "disconnected"
+```
+
+### 列出所有服务器
+
+```typescript
+const servers = mcpComponent.listServers();
+servers.forEach(s => {
+  console.log(`${s.name}: ${s.status} (${s.toolsCount} tools)`);
+});
+```
+
+### 列出所有 MCP 工具
+
+```typescript
+const tools = mcpComponent.listTools();
+tools.forEach(t => {
+  console.log(`- ${t.name}: ${t.description}`);
+});
+```
+
+### 重新加载
+
+```typescript
+await mcpComponent.reload();
+```
+
+## 工具命名
+
+MCP 工具会被注册为 `mcp_{serverName}_{toolName}` 格式：
+
+| MCP Server | MCP Tool | 注册名 |
+|------------|----------|--------|
+| filesystem-mcp | read_file | mcp_filesystem-mcp_read_file |
+| memory | search | mcp_memory_search |
+
+## 错误处理
+
+单个 MCP 服务器的连接失败不会影响其他服务器：
+
+```typescript
+// 服务器状态会记录错误
+const status = mcpComponent.getServerStatus("failed-server");
+if (status?.status === "error") {
+  console.log(`Error: ${status.error}`);
+}
+```
+
+## 类型定义
+
+```typescript
+import type {
+  McpComponentConfig,
+  McpServerConfig,
+  McpServerStatus,
+} from "./mcp";
+```