xuns · Web 服务¶

在浏览器里使用同一套智能体：聊天界面、事件流、工具活动折叠块、文件面板、多会话切换。

xuns .                                   # 所有会话共用当前目录
xuns                                     # 每个会话一个临时工作目录
xuns . --host 0.0.0.0 --port 18960 --base-path /xun

参数¶

参数	形式	默认	说明
`workdir`	位置参数，可选	空	所有会话共用的工作目录；省略或空串时每个会话分配独立临时目录（退出时清理）
`--host`	字符串	`localhost`	监听地址；`0.0.0.0` 时启动信息会额外打印 `aka localhost` 形式
`--port`	整数	`18960`	端口；`0` 表示由系统分配随机端口，实际端口会打印出来
`--token`	字符串	空	访问令牌；空值自动生成 `secrets.token_urlsafe(24)`
`--base-path`	字符串	空	URL 前缀，用于子路径部署；不能包含空段、`.`、`..`
`--manage-sessions` / `--no-manage-sessions`	布尔开关	开启	是否允许在界面中创建/删除会话

对应的 Python API：

from xun import web_session

web_session(workdir=".", host="localhost", port=18960, token="", base_path="", manage_sessions=True)

启动后打印每个会话的直达地址（令牌已带在查询串里）：

Agents are available at the following URLs:
http://localhost:18960/chat/?session=/&token=...

令牌与登录¶

--token 是访问凭据，服务端用 hmac.compare_digest 比对，接受三种携带方式：

Authorization: Bearer <token>
Cookie xun_web_token（登录页或 ?token= 访问 /chat/ 后写入，HttpOnly + SameSite=Strict，HTTPS 下加 Secure）
?token=<token> 查询串

未认证的页面请求会 303 跳转到登录页 --base-path/login；未认证的 API 请求返回 401 {"detail":"Not authenticated"}；未认证的 WebSocket 以 1008 关闭。文档站点 /docs/ 免登录，便于浏览手册。

路由一览¶

以下路径均带 --base-path 前缀（未设置时为空）。

路径	说明
`/`	重定向到 `/chat/`
`/chat/`	前端界面（静态资源，构建自 `web/`）
`/docs/`	中英双语文档站点（打包在 `src/xun/assets/docs`），公开访问
`/login`	登录页，支持 `?next=`
`/api/sessions`	会话列表、创建、删除（`POST /api/sessions/create`、`/remove`）
`/session/`、`/session/<uuid>/`	各会话的后端显示实例（WebSocket `/ws`、`/api/events`、`/api/prompts`、`/api/files/...`）
`/session/<path>/srv/<key>/`	临时静态目录托管，见下

会话状态在列表接口里以 idle / running / waiting 表示（waiting = 有提示待回答）。最后一个会话不能被删除；关闭 --manage-sessions 后创建/删除接口返回 405。

文件面板¶

xuns 启动的会话开启了 expose_files，提供目录浏览、PDF/全屏预览、语法高亮、行内编辑、目录上传（结果通知列出全部文件并自动消失）。所有文件操作被限制在智能体的工作目录内，越界返回 400，符号链接被跳过。

静态目录托管 `/srv/`¶

如果工作目录里生成了一个静态站点（例如本项目的 site/），可以在界面里把它挂成 GET /session/<path>/srv/<key>/：

key 是随机令牌，链接本身即凭据（该路径免令牌）
默认 1 小时过期（SERVE_TTL_SECONDS = 3600），同时最多 16 个（超出返回 429）
不能直接托管工作目录根

部署提示¶

界面与后端通过 WebSocket 通信，反向代理需允许升级请求并保持 X-Forwarded-Host / X-Forwarded-Proto。
子路径部署只需要 --base-path，所有资源与语言切换链接都是相对路径，可挂任意前缀。
--host 0.0.0.0 会把服务暴露到所有网卡，请配合防火墙或反向代理鉴权使用。

前端开发（Vite + Vue DevTools）：

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