安装¶

环境要求¶

Python 3.12 或更高（代码使用 PEP 695 的类型参数语法 def f[T](...)；TypeVar(default=...) 在 3.12 上由 typing_extensions 兜底）
Linux / macOS（bash 工具在 Windows 上不注册，见工具系统）
一个 OpenAI 兼容的模型服务端点

主要运行时依赖：openai、pydantic、aiohttp、fastapi、rich、jinja2、json-repair、markdown、pillow、playwright、docker、html-to-markdown、python-dotenv、puremagic、typing-extensions。

安装¶

pip install xun-agent

如果需要使用内置浏览器工具，再装一次浏览器内核：

playwright install          # 或 playwright install chromium

从源码安装¶

Web 前端资源与文档站点是打包进 src/xun/assets/ 的，从源码安装时若需要 Web 界面，先构建前端：

git clone https://github.com/MenxLi/xun.git
cd xun
make build-web      # cd web && npm i && npm run build，产物写入 src/xun/assets/web
pip install .

Makefile 目标一览

目标	作用
`build-web`	构建 Vue 前端到 `src/xun/assets/web`
`build-docker`	先 `build-web`，再 `docker build -t xun -f docker/Dockerfile .`
`doc`	在容器里按 `docs/AGENTS.md` 生成中英双语文档站点到 `site/`
`doc-update`	与 `doc` 同一条命令，只把提示词换成「按源码最近的变动更新并优化现有文档」
`doc-dist`	把 `site/` 拷进 `src/xun/assets/docs`，供 `xuns` 在 `/docs/` 提供（`site/index.html` 不存在时只提示并跳过）
`doc-clean`	删除 `site/` 与打包目录 `src/xun/assets/docs`（用 `git checkout` 还原其中被跟踪的文件），再删除 `mkdocs.yml`；`docs/` 下的源文件不受影响
`test`	`uv run python -m unittest discover -s test -t . -v`（需要 `uv`）

构建 Docker 镜像¶

xunc 与 xunx 使用名为 xun 的镜像：

make build-docker

镜像基于 ubuntu:24.04，预装 Playwright Chromium、Node、LibreOffice、mkdocs 工具链等，并固定了两个与 xun 相关的环境变量：XUN_HOME=/.xun（宿主 xun home 会在建容器时复制进来，只取 config.json 与 extensions）、_XUN_INFO_TOOL_OVERRIDE=1（此外还设了 locale、VIRTUAL_ENV、PATH 等镜像自身所需变量）。Dockerfile 未声明 ENTRYPOINT/CMD（因此继承 ubuntu:24.04 的 /bin/bash），xunc 会显式传入要执行的命令。

配置¶

Xun 从 $XUN_HOME/config.json 读取配置；XUN_HOME 未设置时是当前工作目录下的 .xun/（不是 ~/.xun）。只写想改的字段即可，缺失字段回落内置默认值：

{
    "model": {
        "name": "my-model"
    }
}

配置支持 ${XUN_...} 占位符，值取自环境变量（因此密钥可以放在 .env 里，加载配置时会自动 load_dotenv()）：

# .env
XUN_OPENAI_BASE_URL=https://api.example.com/v1
XUN_OPENAI_API_KEY=sk-...
XUN_OPENAI_MODEL=        # 留空则自动取服务端返回的第一个模型

配置字段	环境变量	缺失时
`provider.openai_base_url`	`${XUN_OPENAI_BASE_URL}`	启动报 `RuntimeError`
`provider.openai_api_key`	`${XUN_OPENAI_API_KEY}`	启动报 `RuntimeError`
`model.name`	`${XUN_OPENAI_MODEL}`	回落空串 → 自动探测模型
`auto_confirm`	`${XUN_AUTO_CONFIRM}`	回落 `false`

完整字段、合并规则与全部环境变量见配置。

确认提示与自动确认

写文件、执行未列入允许列表的命令等操作默认会要求确认。脚本或 CI 场景可以设 XUN_AUTO_CONFIRM=true（或 /yolo 命令临时切换）。自动确认不会把命令或路径写入允许列表。

验证安装¶

xun "Print the current directory and say hello"

进入交互模式后：

>>> /config        # 看当前生效的配置
>>> /tools         # 看已注册工具
>>> /extensions    # 看扩展及其状态
>>> /help          # 看全部命令

非交互模式（单轮执行，适合脚本与 CI）：

xun --non-interactive "Summarize README.md in one line"

安装后可选内容¶

想做什么	参考
换模型、调温度、设推理力度	配置
加自定义工具/钩子/命令	扩展系统
把智能体嵌进自己的程序	API 指南
部署到容器、开放给多人	xunc、xunx