@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/coder-harness/src/plugins/lsp-plugin.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview LSPPlugin - LSP 代码智能查询插件
+ *
+ * 提供代码智能能力：hover、completion、definition、references 等
+ */
+import type { Diagnostic } from "../types/linter";
+import type { ToolHookContext } from "@ai-setting/roy-agent-core";
+import type { HookContext } from "@ai-setting/roy-agent-core";
+/**
+ * LSP 查询结果类型
+ */
+export interface LSPQueryResult {
+    /** 查询类型 */
+    type: "hover" | "completion" | "definition" | "references" | "diagnostics";
+    /** 文件路径 */
+    filePath: string;
+    /** 结果数据 */
+    data: unknown;
+}
+/**
+ * LSPPlugin 配置
+ */
+export interface LSPPluginConfig {
+    /** 是否启用 */
+    enabled?: boolean;
+    /** 空闲超时（毫秒） */
+    idleTimeout?: number;
+    /** 最大并发连接数 */
+    maxConnections?: number;
+    /** 是否自动下载 LSP 服务器 */
+    autoDownload?: boolean;
+    /** 预加载模式: startup | lazy | disabled */
+    preloadMode?: "startup" | "lazy" | "disabled";
+    /** 预加载的语言列表 */
+    preloadLanguages?: string[];
+}
+/**
+ * LSPPlugin
+ *
+ * 通过 after.tool hook 提供代码智能查询能力
+ *
+ * @example
+ * ```typescript
+ * const plugin = new LSPPlugin({
+ *   enabled: true,
+ *   preloadMode: "startup",  // CLI 启动时预加载
+ *   preloadLanguages: ["typescript", "python"],
+ * });
+ *
+ * // 注册到 ToolComponent
+ * toolComponent.registerHook("after.tool", plugin);
+ * ```
+ */
+export declare class LSPPlugin {
+    private lspManager;
+    private config;
+    private logger;
+    private initialized;
+    constructor(config?: LSPPluginConfig);
+    /**
+     * 初始化 LSP 服务
+     *
+     * 由 PluginHookAdapter 调用，用于启动 LSP 预加载
+     * 内部调用 prewarm() 完成实际预热工作
+     */
+    initialize(): Promise<void>;
+    /**
+     * 预热 LSP 服务（可选手动调用）
+     *
+     * 在 startup 模式下会自动调用，在 lazy 模式下可手动预热
+     */
+    prewarm(languages?: string[]): Promise<void>;
+    /**
+     * 获取 LSP 服务状态
+     */
+    getStatus(): {
+        initialized: boolean;
+        preloadMode: string;
+    };
+    /**
+     * 获取 Hook 点
+     * 与 ToolComponent 的 ToolHookPoints.AFTER_EXECUTE 对应
+     */
+    getHookPoint(): "tool:after.execute";
+    /**
+     * Hook 元信息
+     */
+    get name(): string;
+    get priority(): number;
+    get description(): string;
+    /**
+     * 执行 Hook
+     *
+     * ctx 可以是两种格式：
+     * 1. 直接传入 ToolHookContext（测试场景）
+     * 2. HookManager 包装的 HookContext<ToolHookContext>（实际运行场景）
+     *    - ctx.data 包含 { tool, args, context, result }
+     */
+    onAfterTool(ctx: ToolHookContext | HookContext<ToolHookContext>): Promise<void>;
+    /**
+     * 从工具参数获取目标文件路径
+     */
+    private getTargetFilePath;
+    /**
+     * 将诊断信息附加到结果
+     *
+     * 注意：诊断信息需要 append 到 output 字段，因为只有 output 才会被送进 LLM 上下文
+     */
+    private attachToResult;
+    /**
+     * 格式化诊断信息为可读文本
+     */
+    private formatDiagnostics;
+    /**
+     * 获取严重程度文本
+     */
+    private getSeverityText;
+    /**
+     * 查询文件诊断信息（公开 API）
+     */
+    getDiagnostics(filePath: string): Promise<Diagnostic[]>;
+    /**
+     * 释放资源
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * 创建 LSPPlugin 实例的工厂函数
+ */
+export declare function createLSPPlugin(config?: LSPPluginConfig): LSPPlugin;
+//# sourceMappingURL=lsp-plugin.d.ts.map

package/dist/coder-harness/src/plugins/lsp-plugin.js

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview LSPPlugin - LSP 代码智能查询插件
+ *
+ * 提供代码智能能力：hover、completion、definition、references 等
+ */
+import { createGlobalLSPManager } from "../lsp/manager.js";
+import { createLogger } from "@ai-setting/roy-agent-core";
+/**
+ * LSPPlugin
+ *
+ * 通过 after.tool hook 提供代码智能查询能力
+ *
+ * @example
+ * ```typescript
+ * const plugin = new LSPPlugin({
+ *   enabled: true,
+ *   preloadMode: "startup",  // CLI 启动时预加载
+ *   preloadLanguages: ["typescript", "python"],
+ * });
+ *
+ * // 注册到 ToolComponent
+ * toolComponent.registerHook("after.tool", plugin);
+ * ```
+ */
+export class LSPPlugin {
+    lspManager;
+    config;
+    logger;
+    initialized = false;
+    constructor(config = {}) {
+        this.config = config;
+        this.logger = createLogger("LSPPlugin");
+        console.log(`[LSPPlugin] Constructor called with config:`, config);
+        // 使用全局 LSPManager 单例
+        this.lspManager = createGlobalLSPManager({
+            idleTimeout: config.idleTimeout ?? 60000,
+            maxConnections: config.maxConnections ?? 5,
+            autoDownload: config.autoDownload ?? false,
+        });
+        // 注册进程退出时的清理处理器
+        this.lspManager.registerShutdownHandler();
+        // startup 模式下自动预热
+        if (config.preloadMode === "startup") {
+            const languages = config.preloadLanguages ?? [];
+            this.prewarm(languages);
+        }
+    }
+    /**
+     * 初始化 LSP 服务
+     *
+     * 由 PluginHookAdapter 调用，用于启动 LSP 预加载
+     * 内部调用 prewarm() 完成实际预热工作
+     */
+    async initialize() {
+        const languages = this.config.preloadLanguages ?? [];
+        await this.prewarm(languages);
+    }
+    /**
+     * 预热 LSP 服务（可选手动调用）
+     *
+     * 在 startup 模式下会自动调用，在 lazy 模式下可手动预热
+     */
+    async prewarm(languages) {
+        if (this.initialized) {
+            return;
+        }
+        await this.lspManager.prewarm(languages);
+        this.initialized = true;
+    }
+    /**
+     * 获取 LSP 服务状态
+     */
+    getStatus() {
+        return {
+            initialized: this.initialized,
+            preloadMode: this.config.preloadMode ?? "lazy",
+        };
+    }
+    /**
+     * 获取 Hook 点
+     * 与 ToolComponent 的 ToolHookPoints.AFTER_EXECUTE 对应
+     */
+    getHookPoint() {
+        console.log(`[LSPPlugin] getHookPoint() called, returning: tool:after.execute`);
+        return "tool:after.execute";
+    }
+    /**
+     * Hook 元信息
+     */
+    get name() {
+        return "LSPPlugin";
+    }
+    get priority() {
+        return 90; // 在 LinterPlugin 之前执行
+    }
+    get description() {
+        return "LSP-based code intelligence (hover, completion, definition, etc.)";
+    }
+    /**
+     * 执行 Hook
+     *
+     * ctx 可以是两种格式：
+     * 1. 直接传入 ToolHookContext（测试场景）
+     * 2. HookManager 包装的 HookContext<ToolHookContext>（实际运行场景）
+     *    - ctx.data 包含 { tool, args, context, result }
+     */
+    async onAfterTool(
+    // @ts-expect-error HookContext type mismatch - known issue, HookContext is not generic in this codebase
+    ctx) {
+        // 兼容两种格式：直接传入 ToolHookContext 或包装在 HookContext.data 中
+        const data = "data" in ctx ? ctx.data : ctx;
+        this.logger.info("onAfterTool called, data: " + JSON.stringify(data));
+        const tool = data.tool;
+        const args = data.args || {};
+        const result = data.result;
+        // 获取工具名称
+        let toolName;
+        if (typeof tool === "string") {
+            toolName = tool;
+        }
+        else if (tool && typeof tool === "object") {
+            toolName = tool.name || "";
+        }
+        else {
+            toolName = "";
+        }
+        this.logger.info("Extracted toolName: " + toolName);
+        // 只处理 write_file 和 edit_file（写操作）
+        // read_file 等读操作不需要 LSP 检查
+        if (toolName !== "write_file" && toolName !== "edit_file") {
+            this.logger.info("Skipping non-write tool: " + toolName);
+            return;
+        }
+        this.logger.info("Target tool detected: " + toolName);
+        // 获取目标文件路径
+        const filePath = this.getTargetFilePath(toolName, args);
+        if (!filePath) {
+            this.logger.info("No file path found in args: " + JSON.stringify(args));
+            return;
+        }
+        this.logger.info("File path: " + filePath);
+        // 获取诊断信息（可选增强）
+        try {
+            const diagnostics = await this.lspManager.getDiagnostics(filePath);
+            this.logger.info("diagnostics:" + diagnostics);
+            if (diagnostics.length > 0 && result) {
+                this.attachToResult(result, diagnostics);
+            }
+        }
+        catch (error) {
+            // LSP 错误时 graceful degradation
+            this.logger.warn(`diagnostics failed for ${filePath}: ${error}`);
+        }
+    }
+    /**
+     * 从工具参数获取目标文件路径
+     */
+    getTargetFilePath(toolName, args) {
+        // write_file 和 edit_file 使用 path 参数
+        if (typeof args.path === "string") {
+            return args.path;
+        }
+        // edit_file 旧格式可能使用 filePath 参数
+        if (toolName === "edit_file" && typeof args.filePath === "string") {
+            return args.filePath;
+        }
+        return null;
+    }
+    /**
+     * 将诊断信息附加到结果
+     *
+     * 注意：诊断信息需要 append 到 output 字段，因为只有 output 才会被送进 LLM 上下文
+     */
+    attachToResult(result, diagnostics) {
+        // 构建诊断信息文本
+        const diagnosticText = this.formatDiagnostics(diagnostics);
+        // 将诊断信息 append 到 output
+        if (result.output === undefined) {
+            result.output = diagnosticText;
+        }
+        else if (typeof result.output === "string") {
+            result.output = result.output + "\n\n" + diagnosticText;
+        }
+        else if (typeof result.output === "object") {
+            // 如果 output 已经是对象，添加 diagnostics 字段
+            result.output = {
+                ...result.output,
+                lspDiagnostics: diagnostics,
+                lspDiagnosticText: diagnosticText,
+            };
+        }
+    }
+    /**
+     * 格式化诊断信息为可读文本
+     */
+    formatDiagnostics(diagnostics) {
+        if (diagnostics.length === 0) {
+            return "";
+        }
+        const lines = [];
+        lines.push("## LSP Diagnostics");
+        lines.push(`Found ${diagnostics.length} diagnostic(s):\n`);
+        for (const d of diagnostics) {
+            const severity = this.getSeverityText(d.severity);
+            const { start, end } = d.range;
+            const pos = start.line === end.line
+                ? `Line ${start.line + 1}, Col ${start.character + 1}`
+                : `Lines ${start.line + 1}-${end.line + 1}`;
+            lines.push(`- **[${severity}]** ${d.message}`);
+            lines.push(`  - Location: ${pos}`);
+            if (d.source) {
+                lines.push(`  - Source: ${d.source}`);
+            }
+            if (d.code) {
+                lines.push(`  - Code: ${d.code}`);
+            }
+        }
+        return lines.join("\n");
+    }
+    /**
+     * 获取严重程度文本
+     */
+    getSeverityText(severity) {
+        // DiagnosticSeverity: Error=1, Warning=2, Information=3, Hint=4
+        switch (severity) {
+            case 1: return "Error";
+            case 2: return "Warning";
+            case 3: return "Information";
+            case 4: return "Hint";
+            default: return `Unknown(${severity})`;
+        }
+    }
+    /**
+     * 查询文件诊断信息（公开 API）
+     */
+    async getDiagnostics(filePath) {
+        return this.lspManager.getDiagnostics(filePath);
+    }
+    /**
+     * 释放资源
+     */
+    async dispose() {
+        // 使用全局 LSPManager 的优雅关闭
+        await this.lspManager.dispose();
+    }
+}
+/**
+ * 创建 LSPPlugin 实例的工厂函数
+ */
+export function createLSPPlugin(config) {
+    return new LSPPlugin(config);
+}
+//# sourceMappingURL=lsp-plugin.js.map

package/dist/coder-harness/src/plugins/lsp-plugin.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview LSPPlugin Tests
+ *
+ * 注意: 这个测试文件使用 vi.mock 来模拟 LSPManager。
+ * vi.mock 在 Bun 中是全局的，会影响其他测试文件。
+ * 请确保在 afterAll 中调用 vi.restoreAllMocks() 来清理。
+ */
+export {};
+//# sourceMappingURL=lsp-plugin.test.d.ts.map

package/dist/coder-harness/src/plugins/lsp-plugin.test.js

@@ -0,0 +1,304 @@
+/**
+ * @fileoverview LSPPlugin Tests
+ *
+ * 注意: 这个测试文件使用 vi.mock 来模拟 LSPManager。
+ * vi.mock 在 Bun 中是全局的，会影响其他测试文件。
+ * 请确保在 afterAll 中调用 vi.restoreAllMocks() 来清理。
+ */
+import { describe, it, expect, vi, beforeEach, afterEach, afterAll, beforeAll } from "vitest";
+// Mock LSPManager class - 模拟 LSPManager 以避免启动真实 LSP 服务器
+class MockLSPManager {
+    getDiagnostics = vi.fn().mockResolvedValue([]);
+    dispose = vi.fn().mockResolvedValue(undefined);
+    gracefulShutdown = vi.fn().mockResolvedValue(undefined);
+    initialize = vi.fn().mockResolvedValue(undefined);
+    prewarm = vi.fn().mockResolvedValue(undefined);
+    registerShutdownHandler = vi.fn();
+    getStats = vi.fn().mockReturnValue({
+        activeConnections: 0,
+        prewarmedConnections: 0,
+        totalServers: 0,
+        connections: [],
+    });
+}
+// Store reference for test configuration
+let mockLSPManagerInstance;
+let LSPPlugin;
+describe("LSPPlugin", () => {
+    const defaultConfig = {
+        enabled: true,
+        idleTimeout: 60000,
+        maxConnections: 5,
+    };
+    beforeAll(async () => {
+        // Mock LSPManager module
+        vi.mock("../lsp/manager", () => {
+            const mockInstance = new MockLSPManager();
+            mockLSPManagerInstance = mockInstance;
+            return {
+                LSPManager: class MockLSPManagerClass {
+                    constructor() {
+                        return mockInstance;
+                    }
+                },
+                createGlobalLSPManager: () => mockInstance,
+                getGlobalLSPManager: () => mockInstance,
+                globalLSPManager: mockInstance,
+            };
+        });
+        const module = await import("./lsp-plugin");
+        LSPPlugin = module.LSPPlugin;
+    });
+    let plugin;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Reset the mock instance
+        if (mockLSPManagerInstance) {
+            mockLSPManagerInstance.getDiagnostics = vi.fn().mockResolvedValue([]);
+        }
+    });
+    afterEach(async () => {
+        if (plugin && plugin.dispose) {
+            await plugin.dispose();
+        }
+    });
+    describe("constructor", () => {
+        it("should create plugin with config", () => {
+            plugin = new LSPPlugin(defaultConfig);
+            expect(plugin).toBeDefined();
+        });
+        it("should create LSPManager instance", () => {
+            plugin = new LSPPlugin(defaultConfig);
+            expect(plugin.lspManager).toBeDefined();
+        });
+    });
+    describe("getHookPoint", () => {
+        it("should return tool:after.execute hook point", () => {
+            plugin = new LSPPlugin(defaultConfig);
+            expect(plugin.getHookPoint()).toBe("tool:after.execute");
+        });
+    });
+    describe("onAfterTool", () => {
+        it("should skip non-write operations (e.g., bash)", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "bash" },
+                args: { command: "ls" },
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).not.toHaveBeenCalled();
+        });
+        it("should skip read operations", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "read_file" },
+                args: { path: "/path/to/test.ts" },
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).not.toHaveBeenCalled();
+        });
+        it("should process write_file operation", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "write_file" },
+                args: { path: "/path/to/new.ts", content: "console.log('hello')" },
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).toHaveBeenCalledWith("/path/to/new.ts");
+        });
+        it("should process edit_file operation", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "edit_file" },
+                args: { path: "/path/to/edit.ts", oldString: "foo", newString: "bar" },
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).toHaveBeenCalledWith("/path/to/edit.ts");
+        });
+        it("should handle edit_file with filePath parameter", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "edit_file" },
+                args: { filePath: "/path/to/legacy.ts", oldString: "foo", newString: "bar" },
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).toHaveBeenCalledWith("/path/to/legacy.ts");
+        });
+        it("should attach diagnostics to write_file result output", async () => {
+            const diagnostics = [
+                {
+                    range: {
+                        start: { line: 0, character: 0 },
+                        end: { line: 0, character: 10 },
+                    },
+                    severity: 1,
+                    message: "Unexpected token",
+                },
+            ];
+            plugin = new LSPPlugin(defaultConfig);
+            plugin.lspManager.getDiagnostics = vi
+                .fn()
+                .mockResolvedValue(diagnostics);
+            const result = { success: true, output: "" };
+            const ctx = {
+                tool: { name: "write_file" },
+                args: { path: "/path/to/test.ts", content: "let x = 1" },
+                result,
+            };
+            await plugin.onAfterTool(ctx);
+            // Diagnostics should now be in output (text format)
+            expect(result.output).toBeDefined();
+            expect(typeof result.output).toBe("string");
+            expect(result.output).toContain("LSP Diagnostics");
+            expect(result.output).toContain("Unexpected token");
+            expect(result.output).toContain("1 diagnostic(s)");
+        });
+        it("should handle missing path gracefully", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "read_file" },
+                args: {},
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).not.toHaveBeenCalled();
+        });
+        it("should handle write_file with missing path gracefully", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            const ctx = {
+                tool: { name: "write_file" },
+                args: { content: "some content" },
+                result: { success: true },
+            };
+            await plugin.onAfterTool(ctx);
+            expect(plugin.lspManager.getDiagnostics).not.toHaveBeenCalled();
+        });
+        it("should handle LSP errors gracefully", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            plugin.lspManager.getDiagnostics = vi
+                .fn()
+                .mockRejectedValue(new Error("LSP connection failed"));
+            const ctx = {
+                tool: { name: "write_file" },
+                args: { path: "/path/to/test.ts", content: "let x = 1" },
+                result: { success: true },
+            };
+            // Should not throw - errors are caught internally
+            let errorThrown = false;
+            try {
+                await plugin.onAfterTool(ctx);
+            }
+            catch {
+                errorThrown = true;
+            }
+            expect(errorThrown).toBe(false);
+        });
+    });
+    describe("attachToResult (output formatting)", () => {
+        it("should append diagnostics when output is string", async () => {
+            const diagnostics = [
+                {
+                    range: { start: { line: 1, character: 0 }, end: { line: 1, character: 10 } },
+                    severity: 1,
+                    message: "Syntax error",
+                    source: "typescript",
+                },
+                {
+                    range: { start: { line: 5, character: 5 }, end: { line: 5, character: 15 } },
+                    severity: 2,
+                    message: "Unused variable",
+                },
+            ];
+            plugin = new LSPPlugin(defaultConfig);
+            const result = { success: true, output: "Original content" };
+            // Access private method for testing
+            plugin.attachToResult(result, diagnostics);
+            expect(result.output).toContain("## LSP Diagnostics");
+            expect(result.output).toContain("Found 2 diagnostic(s)");
+            expect(result.output).toContain("**[Error]** Syntax error");
+            expect(result.output).toContain("**[Warning]** Unused variable");
+            expect(result.output).toContain("Line 2, Col 1"); // 1-indexed
+            expect(result.output).toContain("Line 6, Col 6"); // 1-indexed
+            expect(result.output).toContain("Source: typescript");
+            // Original content should be preserved
+            expect(result.output).toContain("Original content");
+        });
+        it("should handle multiple diagnostics in same line", async () => {
+            const diagnostics = [
+                {
+                    range: { start: { line: 0, character: 0 }, end: { line: 0, character: 5 } },
+                    severity: 1,
+                    message: "First error",
+                },
+                {
+                    range: { start: { line: 0, character: 6 }, end: { line: 0, character: 10 } },
+                    severity: 2,
+                    message: "Second warning",
+                },
+            ];
+            plugin = new LSPPlugin(defaultConfig);
+            const result = { success: true, output: "" };
+            plugin.attachToResult(result, diagnostics);
+            expect(result.output).toContain("Found 2 diagnostic(s)");
+            expect(result.output).toContain("First error");
+            expect(result.output).toContain("Second warning");
+        });
+        it("should handle diagnostics with code property", async () => {
+            const diagnostics = [
+                {
+                    range: { start: { line: 0, character: 0 }, end: { line: 0, character: 5 } },
+                    severity: 1,
+                    message: "Error with code",
+                    code: "TS2304",
+                },
+            ];
+            plugin = new LSPPlugin(defaultConfig);
+            const result = { success: true, output: "" };
+            plugin.attachToResult(result, diagnostics);
+            expect(result.output).toContain("Code: TS2304");
+        });
+    });
+    describe("getDiagnostics", () => {
+        it("should return diagnostics from LSPManager", async () => {
+            const diagnostics = [
+                {
+                    range: {
+                        start: { line: 0, character: 0 },
+                        end: { line: 0, character: 10 },
+                    },
+                    severity: 1,
+                    message: "Error",
+                },
+            ];
+            plugin = new LSPPlugin(defaultConfig);
+            plugin.lspManager.getDiagnostics = vi
+                .fn()
+                .mockResolvedValue(diagnostics);
+            const result = await plugin.getDiagnostics("/path/to/test.ts");
+            expect(result).toEqual(diagnostics);
+        });
+    });
+    describe("dispose", () => {
+        it("should dispose LSPManager", async () => {
+            plugin = new LSPPlugin(defaultConfig);
+            await plugin.dispose();
+            expect(plugin.lspManager.dispose).toHaveBeenCalled();
+        });
+    });
+    describe("prewarm", () => {
+        it("should prewarm LSP servers", async () => {
+            plugin = new LSPPlugin({ ...defaultConfig, preloadMode: "lazy" });
+            await plugin.prewarm(["typescript"]);
+            expect(plugin.lspManager.prewarm).toHaveBeenCalledWith(["typescript"]);
+        });
+    });
+});
+afterAll(async () => {
+    vi.restoreAllMocks();
+});
+//# sourceMappingURL=lsp-plugin.test.js.map