Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
import { onUnmounted, ref, type Ref } from 'vue'
import { post } from '@/utils/request'
import { readStoredPtyId, writeStoredPtyId } from '@/utils/sandboxPtyId'
export type SandboxTerminalStatus =
/** 查询到会话沙箱已暂停;唤醒需要用户确认。 */
| 'paused'
| 'connecting'
| 'ready'
/** 查到会话没有运行中的沙箱;创建需要用户确认。 */
| 'needs_provision'
| 'exited'
/** 用户已确认创建,但后端无处可建(智能体没配沙箱后端)。 */
| 'no_sandbox'
| 'unsupported'
| 'idle'
| 'unauthorized'
| 'error'
export type SandboxTerminalControlFrame = {
type: string
code?: string
message?: string
pty_id?: number
backend?: string
reattachable?: boolean
exit_code?: number | null
cols?: number
rows?: number
}
const RECONNECT_BASE_DELAY_MS = 1000
const RECONNECT_MAX_DELAY_MS = 30000
const APP_PING_INTERVAL_MS = 25000
const PENDING_OUTPUT_MAX_BYTES = 1024 * 1024
// 服务端对单个输入帧设了 4 KiB 上限(terminalMaxInputBytes);gorilla 超限时
// 直接关闭连接,而 xterm 的 paste 是整段进 onData 的,粘一段脚本就会掉线。
// 按字节切片后再发:PTY 是字节流,切在多字节字符中间也会被原样按序重组。
const INPUT_FRAME_MAX_BYTES = 2048
function resolveWsBase(): string {
const base = (import.meta.env.BASE_URL || '/').replace(/\/+$/, '')
const protocol = window.location.protocol === 'https:' ? 'wss' : 'ws'
return `${protocol}://${window.location.host}${base}`
}
async function mintTerminalTicket(sessionId: string): Promise<string> {
const res = await post<{ success?: boolean; data?: { ticket?: string } }>(
`/api/v1/sessions/${encodeURIComponent(sessionId)}/sandbox/terminal-ticket`,
{},
)
const ticket = res?.data?.ticket
if (!ticket) {
throw new Error('missing terminal ticket')
}
return ticket
}
/**
* provisionAttempted 决定 SANDBOX_NOT_BOUND 的含义:没带创建意图时只是"还没
* 有沙箱,要不要建一个",带了还失败才是真的无处可建。
*/
function statusFromErrorCode(
code: string | undefined,
provisionAttempted: boolean,
): SandboxTerminalStatus {
if (code === 'SANDBOX_NOT_BOUND') {
return provisionAttempted ? 'no_sandbox' : 'needs_provision'
}
// SANDBOX_STOPPED 是不会暂停的后端(Docker)的同一状态:同样要用户确认才
// 启动,只是提示文案不同,见 sandboxMayBeReclaimed。
if (code === 'SANDBOX_PAUSED' || code === 'SANDBOX_STOPPED') return 'paused'
if (code === 'TERMINAL_UNSUPPORTED') return 'unsupported'
if (code === 'IDLE_DISCONNECTED') return 'idle'
if (code === 'AUTH_REVOKED') return 'unauthorized'
return 'error'
}
export type SandboxTerminalSession = {
status: Ref<SandboxTerminalStatus>
/**
* status 为 paused 时,沙箱是否可能已被回收(后端回的是 SANDBOX_STOPPED)。
* Docker 没有暂停:没在运行的容器要么是停止了,要么已被空闲回收删掉,
* 启动后可能是一个全新的沙箱,不能对用户说"唤醒"。
*/
sandboxMayBeReclaimed: Ref<boolean>
/**
* 最近一次 ready 帧声明的:断线后重连能否接回同一个 shell。Docker 为
* false:断开即结束 shell,重连只会得到新 shell,所以不自动重连,
* 由用户点"重新连接"。
*/
reattachable: Ref<boolean>
/**
* 由 SandboxTerminal.vue 注入:PTY 输出写入 xterm。
* 在 handler 注册前到达的二进制帧会先入队,避免 bash 提示符在 xterm
* 挂载前被丢弃。传入 null 可在卸载时重新开始缓冲。
*/
onOutput: (handler: ((data: Uint8Array) => void) | null) => void
/**
* 连接并打开终端;已在连接中时幂等。
*
* provision 表示"这是用户的显式动作,允许后端创建或唤醒沙箱"。只有点击
* 按钮才应该传 true:创建/唤醒沙箱是要计费的真实基础设施。打开面板时的
* 自动连接一律不带:运行中的沙箱直接挂上,暂停或尚未创建则退回让用户确认。
*/
connect: (options?: { provision?: boolean; cols?: number; rows?: number }) => void
/** 发送键盘输入(xterm onData 的原始字符串)。 */
sendInput: (data: string) => void
/** 同步终端尺寸;ready 后调用。 */
resize: (cols: number, rows: number) => void
/** 断开并停止重连(组件卸载 / 会话切换时调用)。 */
dispose: () => void
}
/**
* 三个参数都必须是活的 ref(`toRef(props, …)`),不能是 `ref(props.x)` 那样的
* 快照:每次 openSocket 都会重读它们,用户切换 agent(含共享来源空间)后的
* 下一次连接才能按新 agent 的沙箱配置去创建沙箱。
*/
export function useSandboxTerminal(
sessionId: Ref<string>,
agentId: Ref<string | undefined>,
agentSourceTenantId: Ref<string | number | null | undefined> = ref(undefined),
): SandboxTerminalSession {
const status = ref<SandboxTerminalStatus>('connecting')
const sandboxMayBeReclaimed = ref(false)
const reattachable = ref(true)
let ws: WebSocket | null = null
let opening = false
// 当前这条连接是否已收到 ready。ready 之前断线时服务端未必开了 shell,
// 照常自动重连;ready 之后断线是否重连取决于 reattachable。
let readyReceived = false
let outputHandler: ((data: Uint8Array) => void) | null = null
let pendingOutput: Uint8Array[] = []
let pendingOutputBytes = 0
let disposed = false
let reconnectAttempt = 0
let reconnectTimer: ReturnType<typeof setTimeout> | null = null
let pingTimer: ReturnType<typeof setInterval> | null = null
let pendingResize: { cols: number; rows: number } | null = null
let pendingGeometry: { cols: number; rows: number } | null = null
// 刷新 / 关面板会拆掉这个闭包;PID 写在 sessionStorage,重挂时才能带 pty_id。
let lastPid: number | null = readStoredPtyId(sessionId.value)
// 当前这次连接是否带创建意图。只由 connect({ provision: true }) 置真。
let allowProvision = false
const textEncoder = new TextEncoder()
function rememberPid(next: number | null) {
lastPid = next
writeStoredPtyId(sessionId.value, next)
}
function clearReconnectTimer() {
if (reconnectTimer !== null) {
clearTimeout(reconnectTimer)
reconnectTimer = null
}
}
function clearPingTimer() {
if (pingTimer !== null) {
clearInterval(pingTimer)
pingTimer = null
}
}
function scheduleReconnect() {
if (disposed) return
clearReconnectTimer()
// 自动重连不得复活已被回收的沙箱:只有用户点击才携带创建意图。掉线期间
// 沙箱如果被回收,重连会拿到 needs_provision,由用户决定是否重建。
allowProvision = false
const delay = Math.min(
RECONNECT_BASE_DELAY_MS * 2 ** reconnectAttempt,
RECONNECT_MAX_DELAY_MS,
)
reconnectAttempt += 1
reconnectTimer = setTimeout(() => {
reconnectTimer = null
void openSocket()
}, delay)
}
async function openSocket() {
if (disposed || opening || ws) return
const sid = sessionId.value
if (!sid) return
opening = true
readyReceived = false
status.value = 'connecting'
try {
const ticket = await mintTerminalTicket(sid)
if (disposed) return
const query = new URLSearchParams({ ticket })
if (allowProvision) {
query.set('provision', '1')
// agent_id 只在允许创建时才有意义:它是首次创建沙箱所用的配置来源。
const agent = agentId.value
if (agent && agent !== 'builtin-quick-answer') {
query.set('agent_id', agent)
}
const sourceTenant = agentSourceTenantId.value
if (sourceTenant != null && String(sourceTenant).trim() !== '') {
query.set('agent_source_tenant_id', String(sourceTenant).trim())
}
}
if (lastPid && lastPid > 0) {
query.set('pty_id', String(lastPid))
}
if (pendingGeometry) {
query.set('cols', String(pendingGeometry.cols))
query.set('rows', String(pendingGeometry.rows))
}
const socket = new WebSocket(
`${resolveWsBase()}/api/v1/sessions/${encodeURIComponent(sid)}/sandbox/terminal?${query.toString()}`,
)
if (disposed) {
socket.close()
return
}
ws = socket
} catch {
ws = null
if (disposed) return
status.value = 'error'
scheduleReconnect()
return
} finally {
opening = false
}
if (!ws) return
ws.binaryType = 'arraybuffer'
ws.onopen = () => {
clearPingTimer()
pingTimer = setInterval(() => {
if (ws && ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: 'ping' }))
}
}, APP_PING_INTERVAL_MS)
}
ws.onmessage = (event) => {
if (typeof event.data === 'string') {
handleControlFrame(event.data)
return
}
const data =
event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : new Uint8Array(0)
deliverOutput(data)
}
ws.onclose = (event) => {
clearPingTimer()
ws = null
if (disposed) return
const reason = typeof event.reason === 'string' ? event.reason : ''
if (
event.code === 1008
|| reason === 'SANDBOX_NOT_BOUND'
|| reason === 'SANDBOX_PAUSED'
|| reason === 'SANDBOX_STOPPED'
|| reason === 'TERMINAL_UNSUPPORTED'
|| reason === 'IDLE_DISCONNECTED'
|| reason === 'AUTH_REVOKED'
) {
if (reason) {
sandboxMayBeReclaimed.value = reason === 'SANDBOX_STOPPED'
status.value = statusFromErrorCode(reason, allowProvision)
} else if (status.value === 'ready' || status.value === 'connecting') {
status.value = 'error'
}
// idle / unauthorized / paused:shell 还在沙箱里,PID 必须留下才能重挂。
// 沙箱没了或后端不支持:PID 已无效,清掉以免下次 Create 撞上死进程。
if (status.value !== 'idle' && status.value !== 'unauthorized' && status.value !== 'paused') {
rememberPid(null)
}
return
}
if (
status.value !== 'needs_provision'
&& status.value !== 'paused'
&& status.value !== 'no_sandbox'
&& status.value !== 'unsupported'
&& status.value !== 'exited'
&& status.value !== 'idle'
&& status.value !== 'unauthorized'
) {
status.value = 'error'
if (readyReceived && !reattachable.value) return
scheduleReconnect()
}
}
ws.onerror = () => {
// onclose 会随后触发,统一在那里处理。
}
}
function handleControlFrame(raw: string) {
let frame: SandboxTerminalControlFrame
try {
frame = JSON.parse(raw)
} catch {
return
}
switch (frame.type) {
case 'ready':
status.value = 'ready'
readyReceived = true
reattachable.value = frame.reattachable !== false
rememberPid(typeof frame.pty_id === 'number' ? frame.pty_id : null)
reconnectAttempt = 0
// 创建意图到此为止。它只用来解释 SANDBOX_NOT_BOUND:连上之前是"还没
// 有沙箱,要不要建",连上之后再收到就一定是"沙箱被回收了"。不复位会
// 把回收误判成 no_sandbox("智能体没配后端"),文案和真实原因无关。
allowProvision = false
if (pendingResize) {
sendResize(pendingResize.cols, pendingResize.rows)
pendingResize = null
}
break
case 'exited': {
status.value = 'exited'
rememberPid(null)
break
}
case 'error': {
sandboxMayBeReclaimed.value = frame.code === 'SANDBOX_STOPPED'
status.value = statusFromErrorCode(frame.code, allowProvision)
if (status.value !== 'idle' && status.value !== 'unauthorized' && status.value !== 'paused') {
rememberPid(null)
}
break
}
default:
break
}
}
function deliverOutput(data: Uint8Array) {
if (data.length === 0) return
if (outputHandler) {
outputHandler(data)
return
}
pendingOutput.push(data)
pendingOutputBytes += data.length
while (pendingOutputBytes > PENDING_OUTPUT_MAX_BYTES && pendingOutput.length > 0) {
const dropped = pendingOutput.shift()
if (dropped) pendingOutputBytes -= dropped.length
}
}
function sendRaw(frame: SandboxTerminalControlFrame) {
ws?.send(JSON.stringify(frame))
}
function sendResize(cols: number, rows: number) {
if (!ws || ws.readyState !== WebSocket.OPEN) {
pendingResize = { cols, rows }
return
}
sendRaw({ type: 'resize', cols, rows })
}
const session: SandboxTerminalSession = {
status,
sandboxMayBeReclaimed,
reattachable,
onOutput(handler) {
outputHandler = handler
if (!handler) return
const queued = pendingOutput
pendingOutput = []
pendingOutputBytes = 0
for (const chunk of queued) {
handler(chunk)
}
},
connect(options) {
if (disposed || ws || opening) return
// 丢掉待触发的自动重连,否则它稍后会带着 provision=false 再拨一次,
// 和用户这次点击抢连接。
clearReconnectTimer()
allowProvision = options?.provision === true
reconnectAttempt = 0
const cols = options?.cols
const rows = options?.rows
pendingGeometry =
cols && rows && cols > 0 && rows > 0 ? { cols, rows } : null
void openSocket()
},
sendInput(data) {
if (!ws || ws.readyState !== WebSocket.OPEN) return
const bytes = textEncoder.encode(data)
for (let offset = 0; offset < bytes.length; offset += INPUT_FRAME_MAX_BYTES) {
ws.send(bytes.subarray(offset, offset + INPUT_FRAME_MAX_BYTES))
}
},
resize: sendResize,
dispose() {
disposed = true
clearReconnectTimer()
clearPingTimer()
if (ws) {
const socket = ws
ws = null
socket.onclose = null
socket.onerror = null
socket.onmessage = null
socket.close()
}
},
}
onUnmounted(() => session.dispose())
return session
}