内置会话入口总览¶

Xun 提供四个控制台脚本（定义在 pyproject.toml 的 [project.scripts]），分别对应四种会话形态。它们的差别只在于把智能体放在哪里运行、以什么方式与人交互，核心执行逻辑完全相同。

[project.scripts]
xun  = "xun:main"
xuns = "xun:main_serve"
xunc = "xun:main_container"
xunx = "xun.supervisor:main"

四种入口对照¶

命令	形态	进程位置	交互界面	典型场景
`xun`	终端会话	当前 Python 进程	终端 REPL（`>>>`）	在当前目录里与智能体协作，改代码、写文档
`xuns`	Web 服务	当前 Python 进程	浏览器聊天界面 + 文件面板	需要浏览器工具、文件上传下载、多会话切换
`xunc`	容器会话	Docker 容器内的 `xuns`	浏览器（端口映射到宿主）	想要隔离环境，或宿主没有 Python 环境
`xunx`	多用户复用服务	宿主编排 + 每用户一个容器	浏览器（按用户名前缀路由）	一台服务器给多人各开一份持久环境

xunc 与 xunx 都在容器里跑 xuns，因此四者实际只有两种智能体运行方式（终端、Web），加上两种部署包装（单容器、多用户网关）。

flowchart LR
  XUN["xun"] --> P1["当前进程<br/>终端 REPL"]
  XUNS["xuns"] --> P2["当前进程<br/>浏览器界面"]
  XUNC["xunc"] --> P3["单个容器<br/>容器内运行 xuns"]
  XUNX["xunx"] --> P4["每用户一个容器<br/>容器内运行 xuns"]

参数一览（速查）¶

xunxunsxuncxunx

参数	默认	说明
`instruction`（位置，可选）	空	首条指令；非交互模式下必填
`--non-interactive`	关闭	单轮执行后退出，适合脚本与 CI

详见 xun · 终端会话。

参数	默认	说明
`workdir`（位置，可选）	空	所有会话共用的工作目录；省略则每个会话一个临时目录
`--host`	`localhost`	监听地址
`--port`	`18960`	监听端口，`0` 表示随机端口
`--token`	随机	访问令牌，空值表示自动生成
`--base-path`	空	URL 前缀（反向代理/子路径部署用）
`--manage-sessions` / `--no-manage-sessions`	开启	是否允许在界面里创建/删除会话
`--initial-agent` / `--no-initial-agent`	开启	是否创建初始智能体；关闭后仍提供界面与 `/docs/` 文档站，无需 LLM 配置

详见 xuns · Web 服务。

参数	默认	说明
`mount`（位置，可选）	不挂载	绑定为容器内 `/workspace` 的宿主目录
`--copy`	关闭	把该目录复制进 `/workspace` 而不是绑定
`--image`	`xun`	使用的镜像
`--name`	`xun-<md5前8位>`	容器名
`--network`	`bridge`	`bridge` 或 `host`
`--port`	`18960`	需要发布的端口，可逗号分隔；`--port ""` 表示不发布
`--env`	空	`NAME=VALUE` 直接赋值，或按通配符转发宿主变量
`--exec`	`xuns . --host 0.0.0.0`（挂载时）	容器内执行的命令，空串表示用镜像默认 CMD

详见 xunc · 容器会话。

子命令	参数	作用
`user-add`	`username`	新增用户并生成随机令牌
`user-del`	`username`	删除用户
`user-list`	—	列出用户、令牌、URL 前缀与期望状态（running / paused）
`pause` / `resume`	`username`	冻结/解冻该用户容器，状态全保留（下一次对账时生效）
`upgrade`	`username ...` / `--all`	标记重建容器（下一次对账时生效）
`serve`	`--host --port --port-range --image --env --interval`	运行网关与编排循环

详见 xunx · 多用户服务。

我该选哪个¶

flowchart TD
  Q1{"需要浏览器界面？"} -->|否| XUN["xun<br/>终端会话"]
  Q1 -->|是| Q2{"需要隔离环境？"}
  Q2 -->|否| XUNS["xuns<br/>本机 Web 服务"]
  Q2 -->|是| Q3{"多人共用？"}
  Q3 -->|否| XUNC["xunc<br/>单容器会话"]
  Q3 -->|是| XUNX["xunx<br/>多用户服务"]

与 Python API 的对应关系¶

入口	等价调用
`xun`	`setup_agent(default_tools=True, default_commands=True)` → `agent.command.register(*cli_commands())`（补上 `/long`、`/render`、`/exit`）→ TTY 下 `interactive_session(agent, instruction)`，`--non-interactive` 时换成 `non_interactive_session`
`xuns`	`web_session(workdir=..., host=..., port=..., token=..., base_path=..., manage_sessions=..., initial_agent=...)`
`xunc`	在容器里执行 `xuns ...`（见 `src/xun/entrypoint.py::main_container`）
`xunx`	`xun.supervisor` 模块：`UserStore` + `DockerManager` + `Supervisor` + `Multiplexer`

嵌入自己的程序时不必经过这些脚本，直接用 setup_agent 或 Agent 即可，见 API 指南。