mcpField
N
nix-profile-manager

nix-profile-manager

github.com/ypares开发3044 次安装今天更新
代码仓库

关于 nix-profile-manager

nix-profile-manager 是一项供 Agent 管理用户指定目录中本地 Nix 配置的技能，可在无需系统级包管理或 sudo 的情况下安装工具。它涵盖包搜索、配置管理和注册表操作。

主要功能

  1. 01管理用户指定的本地配置
  2. 02搜索 Nix 包和 Flake
  3. 03添加、列出及移除包
  4. 04管理 Flake 注册表条目
  5. 05提供故障排查指导

适用场景

  1. 01为 Agent 安装所需工具
  2. 02在配置中查找并管理包
  3. 03排查安装后命令不可用问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ypares/agent-skills --skill nix-profile-manager

安装后在 Claude Code 中输入/nix-profile-manager确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
flakes.md
package-search.md
profile-internals.md
registry.md

详细介绍

面向 Agent 的 Nix Profile 管理器

概述

此技能可让 Agent 在用户提供的目录中维护本地 Nix profile，从而动态安装工具，无需使用系统级包管理或 sudo 权限。

快速入门：设置本地 Profile

用户应提供一个位于其 PATH 中、供 Agent 管理的目录，并确保 AGENT_PROFILE 环境变量包含此目录，以便 Agent 知道该目录的位置。

然后，Agent 只需执行：

nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git"

--profile 标志用于告知 Nix 将 profile 元数据存储在该位置。 Nix 在 profile 中创建的 bin 目录必须位于 PATH 中。

注意：在较旧版本的 Nix 中，add 子命令名为 install。如果出现“add”不存在的错误，请牢记这一点。

核心概念

Profile

profile 是一个包含以下内容的目录：

  • manifest.json - 已安装软件包及其 flake 引用列表
  • bin、lib、share 等目录 - 包含指向 Nix store 中二进制文件、库和文档的符号链接

运行 nix profile add 时，Nix 会更新清单并重新创建符号链接。

Flake

flake 是一种标准化的 Nix 软件包集合，包含：

  • 用于定义输入和输出的 flake.nix 文件
  • 通过 flake.lock 实现的确定性版本控制
  • 多种输出方案（软件包、overlay、模块等）

常见 flake：

  • nixpkgs - 标准软件包库（默认注册表），通常是 github:NixOS/nixpkgs/nixpkgs-unstable 的别名
  • 来自 GitHub 的自定义 flake（例如 github:user/repo）
软件包与 Flake
  • 软件包：单个工具（例如 git、python311）
  • Flake：软件包集合，通过 <flake>#<package> 访问

重要：在某些 flake（例如 nixpkgs）中，软件包可以嵌套：<flake>#<scope>.<package>

基本命令

搜索软件包
# Search in nixpkgs flake:
nix search nixpkgs git

# Search in specific (fully qualified) flake
nix search "github:user/repo[/branch]" <package-name>

# Or get a more detailed JSON output
nix search nixpkgs python3 --json | jq '.[].pname'
管理 Profile
# Add package
nix profile add --profile <profile_path> "<flake>#<package>"

# List installed packages
nix profile list --profile <profile_path>

# Remove by index or element number
nix profile remove --profile <path>/profile 0

# Upgrade packages
nix profile upgrade --profile <profile_path> <package_name>
nix profile upgrade --profile <profile_path> --all  # All packages installed in this profile
管理注册表
# List available flake aliases
nix registry list

# Add custom registry entry (user-level)
nix registry add myflake github:user/repo/branch

常规工作流

# Determine profile path:
echo $AGENT_PROFILE  # If not defined, ask the user which profile to use!!

# Search for the package
nix search nixpkgs git

# Add it
nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git"

# Just use it!
tool-cmd ...

重要细节

  • Profile 路径下的 bin 子目录应位于 PATH 中：包含 profile 的目录必须位于 $PATH 中，才能访问链接的二进制文件
  • Flake 引用不可变：nixpkgs#git 会解析为当前的 nixpkgs 版本；使用 github:user/repo/ref#package 可固定到特定引用
  • Profile 锁定：一次只能由一个 Agent 修改 profile；锁定不会自动进行
  • Store 链接不会过期：即使 flake 发生变化，Nix store 路径仍然有效；必要时，profile 会保留旧的软件包路径

故障排除

找不到软件包：

  • 确认 flake 名称正确：nix registry list 会显示可用别名
  • 使用 nix search <flake> <partial-name> 搜索确切的软件包名称

安装后命令不在 PATH 中：

  • 检查 profile 目录是否位于 $PATH 中：echo $PATH
  • 确认已创建 $AGENT_PROFILE：ls -la $AGENT_PROFILE（根据需要调整路径）

权限被拒绝：

  • 本地 profile 不需要 sudo。如遇权限问题，请告知用户

参考资料

  • references/flakes.md - 深入介绍 flake 概念和 GitHub 引用
  • references/package-search.md - 高级软件包发现技巧
  • references/profile-internals.md - Profile 结构和清单格式
  • references/registry.md - 自定义注册表配置和版本固定

Agent 实现指南

在 Agent 中实现 profile 管理时：

  1. 将 profile 路径作为环境变量或参数接收 - 例如 AGENT_PROFILE 或函数参数
  2. 安装前始终先搜索 - 确认软件包存在且名称准确
  3. 使用 --json 输出进行解析 - 比文本输出更可靠
  4. 妥善处理错误 - 某些 flake 中可能不存在相应软件包
  5. 告知用户 profile 的修改情况 - 帮助用户跟踪已安装的内容

评论

支持 Markdown