Amigo

import { logger } from "@/utils/logger"

import { AmigoServerBuilder } from "@amigo-llm/server";

const server = new AmigoServerBuilder()
  .port(8080)
  .storagePath("./my-storage")
  .build();

server.init();

import { AmigoServerBuilder } from "@amigo-llm/server";

const server = new AmigoServerBuilder()
  // 设置服务器端口（默认 10013）
  .port(8080)
  
  // 设置会话持久化存储路径（默认 ./storage）
  .storagePath("./data")
  
  // 注册自定义工具
  .registerTool(myCustomTool)
  
  // 注册自定义消息类型
  .registerMessage(myCustomMessage)
  
  // 构建服务器实例
  .build();

// 启动服务器
server.init();

import { ServerConfigSchema, type ServerConfig } from "@amigo-llm/server";

// 配置项
interface ServerConfig {
  port: number;              // 端口号 (1-65535)，默认 10013
  storagePath: string;       // 存储路径，默认 "./storage"
  maxConnections?: number;   // 最大连接数（可选）
  heartbeatInterval?: number; // 心跳间隔（可选）
}

// 验证配置
const config = ServerConfigSchema.parse({
  port: 8080,
  storagePath: "./my-storage"
});

interface ToolInterface<K extends ToolNames> {
  name: K;                    // 工具名称（唯一标识）
  description: string;        // 工具描述（LLM 用于理解工具用途）
  whenToUse: string;          // 使用场景说明
  params: ToolParam<K>[];     // 参数定义
  useExamples: string[];      // 使用示例（XML 格式）
  
  invoke: (props: {
    params: ToolParams<K>;                              // 解析后的参数
    getCurrentTask: () => string;                       // 获取当前任务 ID
    getToolFromName: (name: string) => ToolInterface;   // 获取其他工具
    signal?: AbortSignal;                               // 中断信号
    postMessage?: (msg: string | object) => void;       // 发送消息
  }) => Promise<{ message: string; toolResult: ToolResult<K> }>;
}

import { z } from "zod";

export const MyToolSchema = z.object({
  name: z.literal("myTool"),
  params: z.object({
    query: z.string(),
    options: z.object({
      limit: z.number().optional(),
    }).optional(),
  }),
  result: z.object({
    data: z.array(z.string()),
    total: z.number(),
  }),
});

export type MyToolParams = z.infer<typeof MyToolSchema>["params"];
export type MyToolResult = z.infer<typeof MyToolSchema>["result"];

import { createTool } from "./base";
import { logger } from "@/utils/logger";

export const MyTool = createTool({
  name: "myTool",
  description: "执行自定义查询操作",
  whenToUse: "当用户需要查询特定数据时使用此工具",
  
  params: [
    {
      name: "query",
      optional: false,
      description: "查询关键词",
    },
    {
      name: "options",
      optional: true,
      description: "查询选项",
      type: "object",
      params: [
        {
          name: "limit",
          optional: true,
          description: "返回结果数量限制",
        },
      ],
    },
  ],
  
  useExamples: [
    `<myTool>
  <query>搜索关键词</query>
  <options>
    <limit>10</limit>
  </options>
</myTool>`,
  ],
  
  async invoke({ params, signal, postMessage }) {
    const { query, options } = params;
    
    logger.info(`[MyTool] 执行查询: ${query}`);
    
    // 检查中断信号
    if (signal?.aborted) {
      throw new Error("操作已取消");
    }
    
    // 发送进度消息（可选）
    postMessage?.({ type: "progress", data: { status: "processing" } });
    
    // 执行业务逻辑
    const results = await performQuery(query, options?.limit);
    
    return {
      message: `查询完成，找到 ${results.length} 条结果`,
      toolResult: {
        data: results,
        total: results.length,
      },
    };
  },
});

import { MyToolSchema } from "./myTool";

export const toolSchemas = z.discriminatedUnion("name", [
  // ... 其他工具
  MyToolSchema,
]);

import { AmigoServerBuilder } from "@amigo-llm/server";
import { MyTool } from "./tools/myTool";

const server = new AmigoServerBuilder()
  .port(8080)
  .registerTool(MyTool)
  .build();

import { defineMessage } from "@amigo-llm/server";
import { z } from "zod";

// 定义自定义消息
const MyCustomMessage = defineMessage({
  type: "myCustomEvent",
  dataSchema: z.object({
    eventId: z.string(),
    payload: z.any(),
    timestamp: z.number(),
  }),
  // 可选：消息处理器
  handler: async (data) => {
    console.log("收到自定义消息:", data);
  },
});

import { AmigoServerBuilder } from "@amigo-llm/server";

const server = new AmigoServerBuilder()
  .port(8080)
  .registerMessage(MyCustomMessage)
  .build();

import { ToolRegistry, RegistrationError } from "@amigo-llm/server";

const registry = new ToolRegistry();

// 注册工具
registry.register(myTool);

// 获取工具
const tool = registry.get("myTool");

// 检查工具是否存在
if (registry.has("myTool")) {
  // ...
}

// 获取所有工具
const allTools = registry.getAll();

// 获取工具数量
console.log(`已注册 ${registry.size} 个工具`);

import { MessageRegistry } from "@amigo-llm/server";

const registry = new MessageRegistry();

// 注册消息
registry.register(myMessage);

// 获取消息定义
const message = registry.get("myCustomEvent");

// 获取所有消息 Schema（用于合并验证）
const schemas = registry.getAllSchemas();

import { ValidationError, RegistrationError } from "@amigo-llm/server";

try {
  const server = new AmigoServerBuilder()
    .port(99999) // 无效端口
    .build();
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("配置验证失败:", error.details);
  }
}

try {
  registry.register(duplicateTool);
} catch (error) {
  if (error instanceof RegistrationError) {
    console.error("注册失败:", error.message);
  }
}

import path from "node:path";
import dotenv from "dotenv";
import { AmigoServerBuilder, defineMessage } from "@amigo-llm/server";
import { z } from "zod";
import { MyTool } from "./tools/myTool";

dotenv.config();

// 定义自定义消息
const AnalyticsMessage = defineMessage({
  type: "analytics",
  dataSchema: z.object({
    event: z.string(),
    properties: z.record(z.any()),
  }),
});

// 配置
const PORT = Number(process.env.SERVER_PORT) || 10013;
const STORAGE_PATH = process.env.STORAGE_PATH || path.resolve(process.cwd(), "storage");

// 构建服务器
const server = new AmigoServerBuilder()
  .port(PORT)
  .storagePath(STORAGE_PATH)
  .registerTool(MyTool)
  .registerMessage(AnalyticsMessage)
  .build();

// 启动
server.init();

console.log(`Amigo Server 已启动: ws://localhost:${PORT}`);

// 从 @amigo-llm/server 导出
export {
  // 构建器
  AmigoServerBuilder,
  
  // 服务器
  AmigoServer,
  type AmigoServerOptions,
  
  // 配置
  ServerConfigSchema,
  type ServerConfig,
  ValidationError,
  
  // 注册表
  ToolRegistry,
  MessageRegistry,
  RegistrationError,
  
  // 消息定义
  defineMessage,
  type MessageDefinition,
  type MessageSchema,
};

// ✅ 推荐
import { logger } from "@/utils/logger"
import { ConversationManager } from "@/core/conversationManager"

// ❌ 避免
import { logger } from "../../../utils/logger"

// 组件 - PascalCase
ChatWindow.tsx
MessageRenderer.tsx

// 工具函数 - camelCase
parseStreamingXml.ts
createWebSocketServer.ts

// 类型/接口 - PascalCase
interface ConversationState { }
type MessageType = "text" | "tool"

// 常量 - UPPER_SNAKE_CASE
const MAX_RETRY_COUNT = 3
const DEFAULT_PORT = 10013

// 前端 (packages/frontend/src/store/websocket.ts)
console.log("发送消息:", message)

// 后端 (packages/server/src/core/server/index.ts)
console.log("接收消息:", data)

// packages/server/src/core/conversationManager/StreamHandler.ts
console.log("LLM chunk:", chunk.content)

// packages/server/src/core/conversationManager/ToolExecutor.ts
console.log("执行工具:", toolName, params)

// 建议在生产环境添加认证中间件
server.on("upgrade", (req, socket, head) => {
  const token = req.headers["authorization"]
  if (!isValidToken(token)) {
    socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n")
    socket.destroy()
    return
  }
  // 继续 WebSocket 握手
})

// 自动验证，无效参数会抛出错误
const params = YourToolParamsSchema.parse(rawInput)