autosnippet/dist/lib/agent/tools/system-interaction.d.ts

Extract code patterns into a knowledge base for AI coding assistants

/**
 * system-interaction.js — 系统交互工具 (3)
 *
 * 为 Agent 提供与本地操作系统交互的能力:
 *
 * 1. run_safe_command     安全执行终端命令 (受 SafetyPolicy 约束)
 * 2. write_project_file   写入/创建项目文件 (受文件范围约束)
 * 3. get_environment_info 获取运行环境信息
 *
 * ⚠️ 安全设计:
 *   - run_safe_command 在工具层即执行命令黑名单/白名单检查
 *   - write_project_file 在工具层即执行文件路径范围检查
 *   - 两者均依赖 AgentRuntime 注入的 safetyPolicy 上下文
 *   - 即使 safetyPolicy 未注入，工具自身也有基础安全兜底
 *
 * @module system-interaction
 */
import type { ToolHandlerContext } from './_shared.js';
/** SafetyPolicy 安全策略接口 */
interface SafetyPolicy {
    checkCommand(command: string): {
        safe: boolean;
        reason?: string;
    };
    checkFilePath(filePath: string): {
        safe: boolean;
        reason?: string;
    };
}
/** 系统交互工具的 handler 上下文 */
export interface SystemToolContext extends ToolHandlerContext {
    safetyPolicy?: SafetyPolicy;
}
export interface RunSafeCommandParams {
    command: string;
    cwd?: string;
    timeout?: number;
}
export interface WriteProjectFileParams {
    filePath: string;
    content: string;
    append?: boolean;
}
export interface GetEnvironmentInfoParams {
    sections?: string[];
}
export interface EnvironmentInfo {
    os?: Record<string, unknown>;
    node?: Record<string, unknown>;
    git?: Record<string, unknown>;
    project?: Record<string, unknown>;
}
export declare const runSafeCommand: {
    name: string;
    description: string;
    parameters: {
        type: string;
        properties: {
            command: {
                type: string;
                description: string;
            };
            cwd: {
                type: string;
                description: string;
            };
            timeout: {
                type: string;
                description: string;
            };
        };
        required: string[];
    };
    handler: (params: RunSafeCommandParams, ctx: SystemToolContext) => Promise<{
        error: string;
        command?: undefined;
        stdout?: undefined;
        stderr?: undefined;
        exitCode?: undefined;
        cwd?: undefined;
    } | {
        error: string;
        command: string;
        stdout: string;
        stderr: string;
        exitCode?: undefined;
        cwd?: undefined;
    } | {
        exitCode: string | number;
        stdout: string;
        stderr: string;
        command: string;
        cwd: any;
        error?: undefined;
    }>;
};
export declare const writeProjectFile: {
    name: string;
    description: string;
    parameters: {
        type: string;
        properties: {
            filePath: {
                type: string;
                description: string;
            };
            content: {
                type: string;
                description: string;
            };
            append: {
                type: string;
                description: string;
            };
        };
        required: string[];
    };
    handler: (params: WriteProjectFileParams, ctx: SystemToolContext) => Promise<{
        error: string;
        success?: undefined;
        filePath?: undefined;
        absolutePath?: undefined;
        size?: undefined;
        mode?: undefined;
    } | {
        success: boolean;
        filePath: string;
        absolutePath: string;
        size: number;
        mode: string;
        error?: undefined;
    }>;
};
export declare const getEnvironmentInfo: {
    name: string;
    description: string;
    parameters: {
        type: string;
        properties: {
            sections: {
                type: string;
                items: {
                    type: string;
                    enum: string[];
                };
                description: string;
            };
        };
        required: never[];
    };
    handler: (params: GetEnvironmentInfoParams, ctx: ToolHandlerContext) => Promise<EnvironmentInfo>;
};
export {};