Import vendor/dsh-sansheng-liubu/workbench/host/routes.mjs
This commit is contained in:
parent
ca0abaf5a2
commit
b37616221d
|
|
@ -0,0 +1,471 @@
|
|||
// 工作台 HTTP 路由:把 service 暴露给宿主 Web 服务。
|
||||
//
|
||||
// 设计取舍:
|
||||
// - 全部 exact 路由,不做前缀匹配:/sansheng/workbench/xxx 未登记的一律 404,
|
||||
// 不会因为前缀相同就把未知路径交给某个 handler 兜底。
|
||||
// - 非 GET 只接受 POST(其余方法 405),未实现的路径 404,参数错误 400,体过大 413。
|
||||
// - 统一包装 { ok:true, value } / { ok:false, error:{ code, message, details? } },
|
||||
// Content-Type 带 charset、Cache-Control: no-store、Content-Length 手写。
|
||||
// - 事件通道用长轮询而不是 SSE:宿主侧只是一个普通 HTTP handler,
|
||||
// 浏览器刷新/断线重连后靠 since 补齐天然幂等,不需要管连接生命周期;
|
||||
// 最长挂 25 秒,远低于常见代理/浏览器的空闲超时,也不占住宿主的事件循环。
|
||||
// - 任何 ctx.webServer 的缺失都在 registerWorkbenchRoutes 里探测并降级:
|
||||
// 返回一个 no-op 的 dispose,route 列表照常给出,便于诊断而不至于让插件加载失败。
|
||||
|
||||
import { ServiceError } from './service.mjs'
|
||||
|
||||
export const ROUTE_PREFIX = '/sansheng/workbench'
|
||||
|
||||
/** 请求体字节上限:契约里最大的是交接材料(摘录 + 引用),256 KB 足够且能挡住误传大文件。 */
|
||||
export const MAX_BODY_BYTES = 256 * 1024
|
||||
|
||||
/** 长轮询最长挂起时间(毫秒)。浏览器重连后靠 since 补齐,所以不需要真正的无限等待。 */
|
||||
export const DEFAULT_LONG_POLL_MS = 25_000
|
||||
|
||||
/** 轮询间隔:太密会白烧 CPU,太疏会让“有新事件立刻返回”的承诺打折。 */
|
||||
const POLL_INTERVAL_MS = 1_000
|
||||
|
||||
/** 业务错误码 → HTTP 状态码。未列出的统一 400。 */
|
||||
const STATUS_OF_CODE = Object.freeze({
|
||||
INVALID_INPUT: 400,
|
||||
INVALID_ROLE: 400,
|
||||
INVALID_STATE: 400,
|
||||
DISPATCH_INVALID: 400,
|
||||
ATTEMPT_MISMATCH: 400,
|
||||
REPORT_INVALID: 400,
|
||||
NOT_FOUND: 404,
|
||||
CROSS_PROJECT: 409,
|
||||
CONFIG_CONFLICT: 409,
|
||||
SESSION_CONFLICT: 409,
|
||||
DUPLICATE_PROJECT: 409,
|
||||
INTERNAL: 500,
|
||||
})
|
||||
|
||||
function statusOf(error) {
|
||||
if (error instanceof ServiceError) return STATUS_OF_CODE[error.code] ?? 400
|
||||
if (error !== null && typeof error === 'object' && typeof error.code === 'string') {
|
||||
return STATUS_OF_CODE[error.code] ?? 400
|
||||
}
|
||||
return 500
|
||||
}
|
||||
|
||||
/** 响应写出:统一头 + 手写 Content-Length,HEAD 不写体。 */
|
||||
function sendJson(res, status, payload, extraHeaders = undefined) {
|
||||
const body = JSON.stringify(payload)
|
||||
const headers = {
|
||||
'Content-Type': 'application/json; charset=utf-8',
|
||||
'Cache-Control': 'no-store',
|
||||
'Content-Length': Buffer.byteLength(body),
|
||||
...(extraHeaders ?? {}),
|
||||
}
|
||||
res.writeHead(status, headers)
|
||||
res.end(body)
|
||||
return body
|
||||
}
|
||||
|
||||
function sendOk(res, value, extraHeaders) {
|
||||
return sendJson(res, 200, { ok: true, value }, extraHeaders)
|
||||
}
|
||||
|
||||
function sendError(res, error) {
|
||||
const status = statusOf(error)
|
||||
const code = typeof error?.code === 'string' ? error.code : 'INTERNAL'
|
||||
const message = status === 500 && !(error instanceof ServiceError)
|
||||
? '内部错误'
|
||||
: (typeof error?.message === 'string' ? error.message : '请求失败')
|
||||
const payload = { ok: false, error: { code, message } }
|
||||
if (error?.details !== undefined) payload.error.details = error.details
|
||||
return sendJson(res, status, payload)
|
||||
}
|
||||
|
||||
/**
|
||||
* 读请求体:按字节累计,超限立即拒绝(不再继续读,避免被巨大体拖住)。
|
||||
* 空体视为 {},让无参 POST 也能走同一个入口。
|
||||
*/
|
||||
async function readJsonBody(req, limit = MAX_BODY_BYTES) {
|
||||
const chunks = []
|
||||
let total = 0
|
||||
for await (const chunk of req) {
|
||||
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
|
||||
total += buffer.length
|
||||
if (total > limit) {
|
||||
const error = new ServiceError('INVALID_INPUT', `请求体超过 ${limit} 字节上限`, { limit })
|
||||
error.httpStatus = 413
|
||||
throw error
|
||||
}
|
||||
chunks.push(buffer)
|
||||
}
|
||||
const text = Buffer.concat(chunks).toString('utf8').trim()
|
||||
if (text === '') return {}
|
||||
try {
|
||||
const parsed = JSON.parse(text)
|
||||
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
||||
throw new Error('not an object')
|
||||
}
|
||||
return parsed
|
||||
} catch {
|
||||
const error = new ServiceError('INVALID_INPUT', '请求体必须是 JSON 对象')
|
||||
error.httpStatus = 400
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
async function readBody(req, limit) {
|
||||
try {
|
||||
return await readJsonBody(req, limit)
|
||||
} catch (error) {
|
||||
// 体超限与 JSON 非法是 HTTP 层语义,借 httpStatus 覆盖默认映射。
|
||||
if (typeof error.httpStatus === 'number') {
|
||||
const wrapped = new ServiceError(error.code, error.message, error.details)
|
||||
wrapped.httpStatus = error.httpStatus
|
||||
throw wrapped
|
||||
}
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
/** 从 URL 里取查询参数(不依赖宿主框架,纯 node URL)。 */
|
||||
function queryOf(url) {
|
||||
const index = typeof url === 'string' ? url.indexOf('?') : -1
|
||||
if (index < 0) return new URLSearchParams('')
|
||||
const rest = url.slice(index + 1)
|
||||
const hash = rest.indexOf('#')
|
||||
return new URLSearchParams(hash < 0 ? rest : rest.slice(0, hash))
|
||||
}
|
||||
|
||||
function pathOf(url) {
|
||||
if (typeof url !== 'string') return ''
|
||||
const cut = url.search(/[?#]/)
|
||||
return cut < 0 ? url : url.slice(0, cut)
|
||||
}
|
||||
|
||||
/**
|
||||
* 长轮询:最多挂 maxWaitMs,期间每 pollIntervalMs 检查一次是否有新事件;
|
||||
* 一旦有就立刻返回(不等到窗口结束),没有就等到窗口结束返回空列表 + 当前 seq。
|
||||
* 客户端断开(req 触发 close)时立即结束,不留悬挂计时器。
|
||||
*/
|
||||
async function waitForEvents(service, projectId, since, options) {
|
||||
const maxWaitMs = options.longPollMs ?? DEFAULT_LONG_POLL_MS
|
||||
const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS
|
||||
const immediate = service.listEvents(projectId, since, options.eventLimit === undefined ? {} : { limit: options.eventLimit })
|
||||
if (immediate.events.length > 0 || immediate.reset) return immediate
|
||||
const deadline = Date.now() + maxWaitMs
|
||||
while (Date.now() < deadline) {
|
||||
const remain = deadline - Date.now()
|
||||
await sleep(Math.max(1, Math.min(pollIntervalMs, remain)))
|
||||
const fresh = service.listEvents(projectId, since, options.eventLimit === undefined ? {} : { limit: options.eventLimit })
|
||||
if (fresh.events.length > 0 || fresh.reset) return fresh
|
||||
}
|
||||
return service.listEvents(projectId, since, options.eventLimit === undefined ? {} : { limit: options.eventLimit })
|
||||
}
|
||||
|
||||
function sleep(ms) {
|
||||
return new Promise((resolve) => {
|
||||
const timer = setTimeout(resolve, ms)
|
||||
// 计时器不应阻止进程退出(测试里尤其明显)。
|
||||
if (typeof timer.unref === 'function') timer.unref()
|
||||
})
|
||||
}
|
||||
|
||||
/** 统一 handler 包装:方法校验、异常兜底、响应头注入。 */
|
||||
function wrap(handler, { methods = ['POST'], allowBody = true, bodyLimit = MAX_BODY_BYTES } = {}) {
|
||||
return async (req, res) => {
|
||||
try {
|
||||
const method = String(req.method ?? 'GET').toUpperCase()
|
||||
if (!methods.includes(method)) {
|
||||
res.setHeader('Allow', methods.join(', '))
|
||||
sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: `仅支持 ${methods.join(', ')}` } })
|
||||
return
|
||||
}
|
||||
const body = allowBody && method === 'POST' ? await readBody(req, bodyLimit) : {}
|
||||
const url = req.url ?? ''
|
||||
const value = await handler({ req, res, body, method, query: queryOf(url), path: pathOf(url) })
|
||||
// handler 自己已经写过响应(例如长轮询中途断开)时不再写第二遍。
|
||||
if (res.writableEnded === true) return
|
||||
const headers = value !== null && typeof value === 'object' && value.__headers !== undefined ? value.__headers : undefined
|
||||
const payload = headers === undefined ? value : value.payload
|
||||
sendOk(res, payload, headers)
|
||||
} catch (error) {
|
||||
if (res.writableEnded === true) return
|
||||
const status = typeof error?.httpStatus === 'number' ? error.httpStatus : statusOf(error)
|
||||
const code = typeof error?.code === 'string' ? error.code : 'INTERNAL'
|
||||
const payload = { ok: false, error: { code, message: error?.message ?? '请求失败' } }
|
||||
if (error?.details !== undefined) payload.error.details = error.details
|
||||
sendJson(res, status, payload)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 路由表:path → handler 定义。集中声明,便于诊断页一次性列出全部端点。
|
||||
* 每个 handler 都从 body/query 取参数并原样交给 service,不在路由层做业务判断。
|
||||
*/
|
||||
export function buildRouteTable(service, options = {}) {
|
||||
const select = options.projectIdFrom === undefined ? (body) => body.projectId : options.projectIdFrom
|
||||
return Object.freeze({
|
||||
[`${ROUTE_PREFIX}/bootstrap`]: {
|
||||
method: 'GET',
|
||||
handler: async ({ query }) => service.bootstrap(query.get('projectId') ?? undefined),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/project`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.registerProject({
|
||||
hostWorkspaceId: body.hostWorkspaceId,
|
||||
displayNameCache: body.displayNameCache,
|
||||
canonicalRoot: body.canonicalRoot,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/bind`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.bindDepartmentSession({
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
sessionId: body.sessionId,
|
||||
allowReplace: body.allowReplace,
|
||||
creationRequestId: body.creationRequestId,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/config`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.saveDepartmentConfig({
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
provider: body.provider,
|
||||
model: body.model,
|
||||
reasoningEffort: body.reasoningEffort,
|
||||
expectedRevision: body.expectedRevision,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/task`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.createTask({
|
||||
projectId: select(body),
|
||||
title: body.title,
|
||||
objective: body.objective,
|
||||
acceptance: body.acceptance,
|
||||
constraints: body.constraints,
|
||||
scope: body.scope,
|
||||
ownerRoleId: body.ownerRoleId,
|
||||
sourceRoleId: body.sourceRoleId,
|
||||
originMessageRef: body.originMessageRef,
|
||||
returnTarget: body.returnTarget,
|
||||
status: body.status,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/task/cancel`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.cancelTask({
|
||||
projectId: select(body),
|
||||
taskId: body.taskId,
|
||||
reason: body.reason,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/connect`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => {
|
||||
if (typeof options.connect !== 'function') {
|
||||
throw new ServiceError('INVALID_STATE', '宿主未提供会话能力,暂时无法接通部门')
|
||||
}
|
||||
return options.connect({
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
sessionId: body.sessionId,
|
||||
agentPreset: body.agentPreset,
|
||||
})
|
||||
},
|
||||
},
|
||||
[`${ROUTE_PREFIX}/dispatch`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => {
|
||||
const ledger = {
|
||||
projectId: select(body),
|
||||
taskId: body.taskId,
|
||||
idempotencyKey: body.idempotencyKey,
|
||||
sourceRoleId: body.sourceRoleId,
|
||||
targetRoleId: body.targetRoleId,
|
||||
targetSessionId: body.targetSessionId,
|
||||
bindingGeneration: body.bindingGeneration,
|
||||
packet: body.packet,
|
||||
}
|
||||
// 有 Host 会话能力时走 DispatchService:它会真的把任务单送进部门会话,
|
||||
// 并把 prepared → sending → accepted/rejected/unknown 走完。
|
||||
// 没有会话层时只落账(prepared),UI 据此显示“尚未接通”,绝不假装已发送。
|
||||
if (typeof options.dispatch === 'function') {
|
||||
return options.dispatch({
|
||||
...ledger,
|
||||
sourceSessionId: body.sourceSessionId,
|
||||
mode: body.mode,
|
||||
roleName: body.roleName,
|
||||
})
|
||||
}
|
||||
return service.dispatchTask(ledger)
|
||||
},
|
||||
},
|
||||
[`${ROUTE_PREFIX}/ingest`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => {
|
||||
if (typeof options.ingest !== 'function') {
|
||||
throw new ServiceError('INVALID_STATE', '宿主未提供契约解析能力')
|
||||
}
|
||||
return options.ingest({
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
text: body.text,
|
||||
})
|
||||
},
|
||||
},
|
||||
[`${ROUTE_PREFIX}/result`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.reportTaskResult({
|
||||
projectId: select(body),
|
||||
taskId: body.taskId,
|
||||
attemptId: body.attemptId,
|
||||
report: body.report,
|
||||
runTerminal: body.runTerminal,
|
||||
artifactRefs: body.artifactRefs,
|
||||
checks: body.checks,
|
||||
remainingItems: body.remainingItems,
|
||||
blockedReason: body.blockedReason,
|
||||
sourceMessageRef: body.sourceMessageRef,
|
||||
reportVersion: body.reportVersion,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/artifact/revision`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.requestArtifactRevision({
|
||||
projectId: select(body),
|
||||
artifactId: body.artifactId,
|
||||
instruction: body.instruction,
|
||||
ownerRoleId: body.ownerRoleId,
|
||||
sourceRoleId: body.sourceRoleId,
|
||||
title: body.title,
|
||||
acceptance: body.acceptance,
|
||||
constraints: body.constraints,
|
||||
status: body.status,
|
||||
originMessageRef: body.originMessageRef,
|
||||
returnTarget: body.returnTarget,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/artifact`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.registerArtifact({
|
||||
projectId: select(body),
|
||||
taskId: body.taskId,
|
||||
ownerRoleId: body.ownerRoleId,
|
||||
fileRef: body.fileRef,
|
||||
displayName: body.displayName,
|
||||
mediaType: body.mediaType,
|
||||
versionOrHash: body.versionOrHash,
|
||||
verification: body.verification,
|
||||
sourceResultId: body.sourceResultId,
|
||||
revisesArtifactId: body.revisesArtifactId,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/memory/get`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.getMemory({
|
||||
scope: body.scope,
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/memory/put`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.putMemory({
|
||||
scope: body.scope,
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
text: body.text,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/memory/append`]: {
|
||||
method: 'POST',
|
||||
handler: async ({ body }) => service.appendMemory({
|
||||
scope: body.scope,
|
||||
projectId: select(body),
|
||||
roleId: body.roleId,
|
||||
text: body.text,
|
||||
}),
|
||||
},
|
||||
[`${ROUTE_PREFIX}/events`]: {
|
||||
method: 'GET',
|
||||
handler: async ({ query, req, res }) => {
|
||||
const projectId = query.get('projectId') ?? undefined
|
||||
const since = Number(query.get('since') ?? 0)
|
||||
if (query.get('since') !== null && !Number.isFinite(since)) {
|
||||
throw new ServiceError('INVALID_INPUT', 'since 必须是数字', { field: 'since' })
|
||||
}
|
||||
const immediateOnly = query.get('wait') === '0'
|
||||
if (immediateOnly || (options.longPollMs ?? DEFAULT_LONG_POLL_MS) <= 0) {
|
||||
return service.listEvents(projectId, since, { limit: options.eventLimit })
|
||||
}
|
||||
return waitForEvents(service, projectId, since, {
|
||||
...options,
|
||||
// 客户端断开时不再等满窗口:把当前结果写回去(或让外层发现已结束)。
|
||||
onAbort: () => {
|
||||
if (res.writableEnded !== true && res.destroyed !== true) {
|
||||
sendOk(res, service.listEvents(projectId, since, { limit: options.eventLimit }), { Connection: 'close' })
|
||||
}
|
||||
},
|
||||
})
|
||||
},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* 注册路由。宿主没有 webServer(或没有 register)时返回 no-op dispose,
|
||||
* 并在返回值上标 registered:false,调用方可据此提示“宿主不支持工作台接口”。
|
||||
*
|
||||
* @returns {() => void} dispose:卸载全部已注册路由;重复调用无副作用。
|
||||
*/
|
||||
export function registerWorkbenchRoutes(ctx, service, options = {}) {
|
||||
const disposes = []
|
||||
const server = ctx?.webServer
|
||||
if (server === undefined || server === null || typeof server.register !== 'function') {
|
||||
const noop = () => {}
|
||||
noop.registered = false
|
||||
noop.reason = '宿主未提供 webServer.register'
|
||||
return noop
|
||||
}
|
||||
const table = buildRouteTable(service, options)
|
||||
const bodyLimit = options.maxBodyBytes ?? MAX_BODY_BYTES
|
||||
try {
|
||||
for (const [path, def] of Object.entries(table)) {
|
||||
const methods = def.method === 'GET' ? ['GET'] : ['POST']
|
||||
const handler = wrap(def.handler, { methods, allowBody: def.method === 'POST', bodyLimit })
|
||||
const dispose = server.register({ kind: 'exact', path, handler })
|
||||
if (typeof dispose === 'function') disposes.push(dispose)
|
||||
}
|
||||
} catch (error) {
|
||||
// 部分注册失败:先把已注册的回滚,避免留下半套路由(前端会看到一多半 404)。
|
||||
for (const dispose of disposes.reverse()) {
|
||||
try {
|
||||
dispose()
|
||||
} catch {
|
||||
// 卸载失败不影响主流程:宿主要么已卸载,要么进程即将重启。
|
||||
}
|
||||
}
|
||||
throw error
|
||||
}
|
||||
let disposed = false
|
||||
const dispose = () => {
|
||||
if (disposed) return
|
||||
disposed = true
|
||||
for (const fn of disposes.reverse()) {
|
||||
try {
|
||||
fn()
|
||||
} catch {
|
||||
// 同上:dispose 必须幂等且不抛。
|
||||
}
|
||||
}
|
||||
}
|
||||
dispose.registered = true
|
||||
dispose.paths = Object.keys(table)
|
||||
return dispose
|
||||
}
|
||||
|
||||
/** 供诊断页使用:列出全部端点与其方法。 */
|
||||
export function listWorkbenchRoutes() {
|
||||
return Object.entries(buildRouteTable({ bootstrap: () => null }, {})).map(([path, def]) => ({ path, method: def.method }))
|
||||
}
|
||||
Loading…
Reference in New Issue