@ai-setting/roy-agent-core 1.3.9 → 1.3.11

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

@@ -1,162 +0,0 @@
-/**
- * @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

@@ -1,63 +0,0 @@
-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

@@ -1,172 +0,0 @@
-/**
- * @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

@@ -1,244 +0,0 @@
-# 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";
-```