安装¶

环境要求¶

Python 3.12 以上（源码使用 PEP 695 语法）
一个 OpenAI 兼容的模型服务端点
使用默认浏览器工具时需要 Playwright 浏览器；使用 apply_patch 工具时需要 Git

从 PyPI 安装¶

pip install xun-agent

# 默认浏览器工具依赖 Playwright 浏览器
playwright install

# 模型服务配置
export XUN_OPENAI_BASE_URL="https://api.example.com/v1"
export XUN_OPENAI_API_KEY="your-api-key"
export XUN_OPENAI_MODEL="your-model"

# 交互式会话
xun

# 或 Web 服务
xuns .

模型名可以留空

未设置 XUN_OPENAI_MODEL 时，Agent.initialize() 会调用 models.list() 取第一个可用模型并给出提示。配置字段的完整含义见 Config 字段与配置。

安装后可以用下面的方式确认入口命令与版本：

xun -h
xune            # 列出声明了 CLI 的扩展，没有则提示为空
python -c "from xun import xun_version; print(xun_version())"

从源码安装¶

Web 前端产物随包分发，构建前需要先编译一次：

git clone https://github.com/MenxLi/xun.git
cd xun
make build-web      # 等价于 cd web && npm i && npm run build
pip install .

前端开发模式（同时起后端与 Vite）：

cd web
npm install
npm run dev         # http://127.0.0.1:5173

构建 Docker 镜像¶

xunc 与 xunx 依赖同一个镜像，镜像里已经带好 Python、Node、Rust、ffmpeg 与 Playwright 浏览器。

make build-docker   # 先 make build-web，再 docker build -t xun -f docker/Dockerfile .

构建完成后即可沙箱运行：

xunc                # 容器内使用临时工作区
xunc .              # 把当前目录绑定挂载为 /workspace
xunc --copy .       # 改为复制进 /workspace
xunc --exec "xun"   # 在容器里跑命令行入口而不是 Web

参数、多用户网关与环境变量转发的完整说明见沙箱与多用户 xunc / xunx。

文档随包分发¶

构建好的站点会被复制进 src/xun/assets/docs/，因此 PyPI 发行版自带双语文档。启动 xuns / xunc 后访问 /docs/ 即可浏览；没有配置模型服务时可以用：

xuns --no-initial-agent
# 然后访问 http://localhost:18960/docs/

重新生成站点（需要 Docker 与已安装的镜像）见仓库根的 README-BUILD-DOCS.md。

配置文件位置¶

配置从 $XUN_HOME/config.json 读取，XUN_HOME 未设置时为 ./.xun/config.json。同一个目录下还会存放扩展、扩展数据与会话存档：

$XUN_HOME/
├── config.json          # 智能体配置
├── extensions/          # 扩展源文件，见插件开发指南
├── extension_data/      # 各扩展的私有数据目录
├── skills/              # Skills 扩展的技能包
├── conversation/        # /save 与 /load 的会话存档
└── x/                   # xunx 的用户数据库

字段级说明见 Config 字段与配置。