nixai: NixOS AI 助手

'nixai' 是一个强大的命令行工具，旨在帮助 NixOS 用户解决配置问题、诊断错误、管理系统和软件包，并生成 Nix 表达式，所有这些都由大型语言模型 (LLM) 提供支持，并结合了官方和社区文档。其核心优势在于能够理解 NixOS 特定的上下文，提供更精确的帮助。

主要功能点

直接提问: 像与 AI 聊天一样，直接用自然语言询问 NixOS 相关问题。
错误诊断: 分析 NixOS 构建或系统日志，识别问题并提供解决方案。
搜索与解释: 搜索 Nix 包或服务，并获取 AI 生成的配置选项解释和使用示例（支持 NixOS 和 Home Manager）。
配置管理: AI 辅助查看、设置、修改、分析和优化 Nix 配置。
打包分析: 自动分析 Git 仓库，检测构建系统和依赖，并生成 Nix 表达式（derivation）。
系统健康检查: 执行全面的系统检查，并提供 AI 分析报告。
升级建议: 提供 NixOS 系统升级的指导、检查和步骤建议。
交互模式: 提供一个交互式 shell，方便连续操作和调试。

安装步骤

推荐使用 Nix flakes 进行安装，这将提供一个隔离且可重现的环境。

使用 Nix (推荐)

在您的 'flake.nix' 文件中添加 'nixai' 作为输入：

{
  description = "Your system configuration";

  inputs = {
    # ... other inputs
    nixai.url = "github:olafkfreund/nix-ai-help";
    # Or for a specific version:
    # nixai.url = "github:olafkfreund/nix-ai-help/vX.Y.Z"; # Replace X.Y.Z with a tag

    # If you use Home Manager as a flake input
    home-manager.url = "github:nix-community/home-manager"; # Ensure Home Manager input is present
    # ...
  };

  outputs = { self, nixpkgs, nixai, ... }@inputs: {
    # For NixOS configuration
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      specialArgs = { inherit inputs; };
      modules = [
        # ... your modules
        nixai.nixosModules.nixai # Enable the nixai module
        # ...
      ];
    };

    # For Home Manager configuration (as a standalone module)
    homeConfigurations."youruser@yourhostname" = inputs.home-manager.lib.homeManager {
      pkgs = nixpkgs.legacyPackages.x86_64-linux; # Or your system's pkgs
      extraSpecialArgs = { inherit inputs; };
      modules = [
        # ... your modules
        nixai.homeManagerModules.nixai # Enable the nixai module for Home Manager
        # ...
      ];
    };
  };
}

然后运行：

# For NixOS system (as root)
sudo nixos-rebuild switch --flake /path/to/your/config#yourhostname

# For Home Manager (as user)
nixos-rebuild switch # If HM is part of system
# OR (if standalone)
home-manager switch --flake /path/to/your/config#youruser@yourhostname

或者，如果您想直接构建和运行：

nix run github:olafkfreund/nix-ai-help -- help
# Or to run a specific command:
nix run github:olafkfreund/nix-ai-help -- diagnose <args>

使用 Go

确保您安装了 Go 1.24+ 和 Nix。

克隆仓库: 'git clone https://github.com/olafkfreund/nix-ai-help.git'
进入目录: 'cd nix-ai-help'
构建: 'go build -o nixai ./cmd/nixai/main.go'
运行: './nixai help'

服务器配置 (供 MCP 客户端使用)

'nixai' 内部包含一个 MCP 服务器组件，用于托管和查询 NixOS 文档。这个服务器作为 'nixai' 主程序的一个子命令运行。如果您的 MCP 客户端框架需要连接到这个服务器，您需要配置它来执行 'nixai mcp-server start' 命令。

以下是一个示例配置（具体格式取决于您的 MCP 客户端框架）：

{
  "server_name": "NixAI Documentation Server",
  "description": "Provides NixOS and Home Manager documentation via HTTP/JSON.",
  "command": "nixai",
  "args": ["mcp-server", "start", "-d"],
  "host": "localhost",  // 服务器启动后监听的主机
  "port": 8080,         // 服务器启动后监听的端口 (可在 ~/.config/nixai/config.yaml 中配置)
  "protocol": "http"    // 当前实现使用 HTTP 而非 JSON-RPC
  // ... 其他客户端可能需要的字段，例如能力声明等
}

说明：

'"command": "nixai"'：指定执行 'nixai' 程序作为服务器。
'"args": ["mcp-server", "start", "-d"]'：传递给 'nixai' 的参数，启动 MCP 服务器子命令，'-d' 表示在后台运行。
'"host": "localhost"' 和 '"port": 8080'：这是 'nixai' MCP 服务器默认监听的地址。MCP 客户端需要连接到这个地址。请确保 '~/.config/nixai/config.yaml' 中的 MCP 服务器配置与此匹配，或者根据您的实际配置调整。
'"protocol": "http"'：此服务器实现使用的是简单的 HTTP/JSON 协议，而不是标准的 JSON-RPC 协议。

请注意，上述 JSON 格式是一个示例，用于说明 MCP 客户端如何配置以启动和连接到 'nixai' 的 MCP 服务器。您需要根据您的 MCP 客户端框架的要求来调整实际的配置格式。在大多数情况下，您可以直接运行 'nixai mcp-server start -d' 来启动服务器，然后您的 MCP 客户端（如果支持配置 MCP 服务器地址的话）连接到 'localhost:8080'。

基本使用方法

直接提问

nixai "如何在 NixOS 中启用 SSH？"
# 或使用 --ask 标志
nixai --ask "什么是 Nix flake？"

诊断错误

# 分析日志文件
nixai diagnose --log-file /var/log/nixos-rebuild.log

# 分析 nix log 的输出
nixai diagnose --nix-log # 或 nixai diagnose --nix-log < derivation-or-path >

# 分析通过管道输入的日志
journalctl -u nginx.service | nixai diagnose

解释配置选项

# 解释 NixOS 系统选项
nixai explain-option services.nginx.enable

# 解释 Home Manager 选项
nixai explain-home-option programs.git.enable

# 使用自然语言提问
nixai explain-option "如何配置防火墙？"

搜索包或服务

nixai search pkg firefox
nixai search service nginx

运行健康检查

nixai health

使用交互模式

nixai interactive

进入交互模式后，输入 'help' 查看可用命令。

关键词