交互式入口 xun / xuns¶
Xun 安装后提供五个控制台命令，都在 pyproject.toml 的 [project.scripts] 中声明：
| 命令 | 入口函数 | 形态 | 适用场景 |
|---|---|---|---|
xun |
xun:main |
终端会话 | 在当前目录里交互式干活 |
xuns |
xun:main_serve |
Web 服务 | 浏览器界面、文件面板、多会话 |
xunc |
xun:main_container |
容器会话 | 把 xuns / xun 关进 Docker 沙箱 |
xunx |
xun.supervisor:main |
多用户网关 | 一个端口服务多个用户容器 |
xune |
xun.extension:main_extension |
扩展 CLI | 直接运行某个扩展自带的命令行 |
xun 与 xuns 共用同一套会话实现，差别只在显示层：前者是控制台显示 Display，后者是 WebDisplay。
xun：终端会话¶
xun # 进入交互循环，工作目录为当前目录
xun "把 hello.py 写成 hello world" # 带初始指令进入
xun --non-interactive "只回答一句话：1+1=?" # 单轮执行，打印结果后退出
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
instruction |
位置参数 | "" |
进入会话时的第一条指令 |
--non-interactive |
开关 | 关 | 单轮执行后退出，不进入交互循环 |
输入方式¶
- 直接输入文本即为用户消息；
/名字 参数为会话命令。 - 图片附件写成
[image:路径 或 URL]，可一次放多个：>>> [image:cat.png image:https://example.com/dog.png] 比较这两张图（需要model.capabilities含vision，否则智能体会报错而不是静默忽略。） - 输入行编辑由 prompt_toolkit 提供：
Up搜索历史、/补全斜杠命令、@补全文件路径。 - 确认提示可以在输入中途弹出，回答后原输入原样恢复。
Ctrl+C中断当前执行；/exit退出会话，/long进入多行输入模式。
内置会话命令¶
/help 会列出当前入口实际注册的命令。命令分三组注册。
通用命令（所有入口）
| 命令 | 作用 |
|---|---|
/help |
列出已注册命令 |
/tools |
列出已注册工具 |
/history |
显示历史 |
/tokens |
显示当前会话 token 用量 |
/config |
查看配置；/config model.name=my-model 修改（不落盘） |
/compact [toolcall] |
压缩会话；带 toolcall 时只回收工具结果 |
/continue |
继续执行 |
/retry |
重发上一条消息 |
/revise [新内容] |
不带参数则删除最后一条用户消息并等待重新输入；带参数则替换它 |
/clear [all] |
清空会话历史；all 同时清理临时文件 |
/yolo |
切换全局自动确认 |
/extensions |
列出扩展及其状态 |
读写工作区相关命令（只在带内置工具的交互式入口注册：xun、xuns）
| 命令 | 作用 |
|---|---|
/save / /load latest\|<序号> |
会话存档的保存与载入（实验特性） |
/render <文件> |
把当前会话历史渲染成独立 HTML 保存 |
/handoff |
把当前会话打包成 zip 交接包，并注入接手提示 |
策略命令（仅在装载内置工具时注册）
/policy 管理内置工具的写权限与命令允许列表，子命令为
cmd_allowlist、cmd_allowlist_add <命令>、cmd_allowlist_remove <命令>，
以及对应的 path_allowlist* 三个变体。这些允许列表是运行时状态，不写入配置文件。
命令与写文件的确认
危险命令直接拒绝而不进入确认，其余按命令行结构逐项判定，判定结论附简要原因。 详见 工具设置。
xuns：Web 服务¶
xuns # 临时工作区，每个会话各自一个
xuns . # 固定工作区，所有会话共用
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
workdir |
位置参数 | 无 | 工作区目录；省略则每个会话使用独立临时目录 |
--host |
str | localhost |
监听地址 |
--port |
int | 18960 |
端口；0 表示由系统分配 |
--token |
str | 随机 | 访问令牌，缺省生成 24 字节 urlsafe token |
--base-path |
str | "" |
URL 前缀，用于挂在反向代理子路径下 |
--manage-sessions / --no-manage-sessions |
开关 | 开 | 是否允许在界面上新建 / 删除会话 |
--initial-agent / --no-initial-agent |
开关 | 开 | 是否在启动时创建初始智能体 |
启动后终端会打印带令牌的访问地址，形如 http://localhost:18960/chat/?session=/&token=…；
浏览器打开后令牌被写入 Cookie，地址栏中的令牌随即由一次 303 重定向清掉。
路由¶
| 路径 | 内容 | 是否需要令牌 |
|---|---|---|
/chat/ |
Web 前端（Vue 单页应用） | 需要 |
/session/<挂载点>/… |
该会话显示层的后端接口与 WebSocket | 需要 |
/api/sessions |
会话列表与新建 / 删除 / 重命名 | 需要 |
/docs/ |
随包分发的双语文档 | 不需要（仅 GET / HEAD） |
/srv/<随机键>/… |
临时托管的工作目录站点，默认 1 小时过期 | URL 自带随机键 |
/login |
令牌登录页 | 不需要 |
因此「只想看文档」时可以完全不配模型：xuns --no-initial-agent 后访问 /docs/。
会话与智能体的关系¶
一个会话等于一个挂载点、一个 WebDisplay，各自持有独立的事件缓冲、待答提示与文件策略；
一个显示层可以绑定多个智能体，界面上用顶部下拉框切换。
xuns <目录> 时所有会话共用同一个工作目录；省略参数时每个会话得到自己的临时目录，会话删除即清理。
程序内挂载方式见 WebDisplay 挂载。
项目指令
智能体会读取工作目录下的 AGENTS.md 并作为系统提示的独立段落加载。
想关掉它，设置 load_project_instructions: false。
相关入口¶
- 想把上面的会话放进容器或多用户环境：沙箱与多用户 xunc / xunx。
- 想直接跑扩展自带的命令：扩展 CLI 入口 xune。