diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index e6fdf0b..5136bbd 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -4,6 +4,23 @@ fn greet(name: &str) -> String { format!("Hello, {}! You've been greeted from Rust!", name) } +/// 探测 tts-hub 控制通道端口是否可连(UI-1b,施工方案 v0.8.0 §8.2 方案 C)。 +/// +/// HubLauncher 启动时先经此命令做 TCP 探测(127.0.0.1:port),不通则弹引导对话框。 +/// 只测端口连通性,不读 HTTP——版本 / appMode 由前端 `GET /v1/status` 再确认。 +/// 返回 Ok(true)=端口可连,Ok(false)=不可连;参数非法时 Err(描述)。 +/// JS 侧经 `invoke("check_hub", { port, timeoutMs })` 调用(Tauri 2 自动 camelCase↔snake_case)。 +#[tauri::command] +fn check_hub(port: u16, timeout_ms: u64) -> Result { + use std::net::{SocketAddr, TcpStream}; + use std::time::Duration; + + let addr: SocketAddr = format!("127.0.0.1:{port}") + .parse() + .map_err(|e| format!("invalid address 127.0.0.1:{port}: {e}"))?; + Ok(TcpStream::connect_timeout(&addr, Duration::from_millis(timeout_ms)).is_ok()) +} + /// 检测系统是否安装 WebView2 Runtime。 /// /// 实现:查注册表 `HKLM\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}`, @@ -65,7 +82,7 @@ pub fn run() { } Ok(()) }) - .invoke_handler(tauri::generate_handler![greet]) + .invoke_handler(tauri::generate_handler![greet, check_hub]) .run(tauri::generate_context!()) .expect("error while running tauri application"); } diff --git a/src/App.tsx b/src/App.tsx index a660aa6..942a7cb 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -1,20 +1,27 @@ /** - * App.tsx — UI-1a 状态机 + * App.tsx — UI-1a 状态机 + UI-1b hub 接入 * * 职责: + * - UI-1b:caps === null → (探测 39995 / 引导启动 / 版本兼容门); + * 验证通过后经 HubContext.Provider 下发 client 单例 + caps,渲染 Frame + 当前路由 * - 持有 activeLayer(0..4),渲染 Frame + LayerNav + LegendBar + 当前路由 + SignBlock + ConfirmGate - * - 演示数据:图名 mypack / 版本 v1.3·main / SignBlock 占位 / ConfirmGate 演示 + * - caps 就绪后轮询 /v1/status → 真实连接状态 → Frame 状态行 * - * UI-1b 在此接入: - * - 启动时调 /v1/status → 真实连接状态 → 替换 Frame 状态行 / LayerNav 圆点色 - * - hubCapabilities → 决定 SignBlock 哪些工序可用、ConfirmGate 真实触发条件 + * UI-2/3/4 在此接入: + * - LayerNav 圆点按真实工作面状态计算(现仍为演示硬编码) + * - ConfirmGate 接真实 /v1/push confirm:true;死链 / 待签数接真实数据 */ -import { useState } from "react"; +import { useEffect, useState } from "react"; import Frame from "./components/Frame"; import LayerNav, { LayerItem } from "./components/LayerNav"; import LegendBar from "./components/LegendBar"; import SignBlock from "./components/SignBlock"; import ConfirmGate from "./components/ConfirmGate"; +import HubLauncher from "./components/HubLauncher"; + +import { HubContext, hubClient } from "./hub/HubContext"; +import type { HubCapabilities } from "./hub/capabilities"; +import type { HubStatus } from "./hub/client"; import Overview from "./routes/Overview"; import Code from "./routes/Code"; @@ -34,6 +41,8 @@ const LAYERS: LayerItem[] = [ const PACK = { name: "mypack", version: "v1.3", branch: "main" }; +const STATUS_POLL_MS = 30_000; + const SIGN_CHECKS = [ { k: "版本", v: "v1.3 · 已生成", tone: "ok" as const }, { k: "校样", v: "3 处差异", tone: "bad" as const, next: true }, @@ -54,9 +63,31 @@ const DEMO_CONFIRM_ITEMS = [ ]; function App() { + const [caps, setCaps] = useState(null); + const [status, setStatus] = useState(null); const [activeLayer, setActiveLayer] = useState("overview"); const [confirmOpen, setConfirmOpen] = useState(false); + // caps 就绪后轮询 /v1/status:真实 TTS 连接状态 → Frame 状态行 + useEffect(() => { + if (caps === null) return; + let cancelled = false; + const refresh = async () => { + try { + const s = await hubClient.status(); + if (!cancelled) setStatus(s); + } catch { + if (!cancelled) setStatus(null); + } + }; + void refresh(); + const timer = window.setInterval(() => void refresh(), STATUS_POLL_MS); + return () => { + cancelled = true; + window.clearInterval(timer); + }; + }, [caps]); + const routeElement = (() => { switch (activeLayer) { case "overview": return ; @@ -67,10 +98,17 @@ function App() { } })(); + // caps 未就绪:先过 HubLauncher(探测 / 引导 / 版本兼容门) + if (caps === null) { + return ; + } + return ( - <> + setConfirmOpen(false)} onConfirm={() => { - // UI-1a:演示确认(不真实调 hub);UI-1b 在此接 /v1/push confirm:true + // UI-2 在此接真实 /v1/push confirm:true(hubClient.push(root, true)) setConfirmOpen(false); }} /> - + ); } diff --git a/src/components/Frame.css b/src/components/Frame.css index c24b9fe..949c154 100644 --- a/src/components/Frame.css +++ b/src/components/Frame.css @@ -110,7 +110,11 @@ } .frame-status-dot { - color: var(--ok); /* 已连接 = 青色 */ + color: var(--ok); /* 已连接 = 青色(§2.5) */ +} + +.frame-status-dot.off { + color: var(--red); /* 未连接 = 红色(§2.5) */ } .frame-status-right { diff --git a/src/components/Frame.tsx b/src/components/Frame.tsx index 90c6d94..659caa1 100644 --- a/src/components/Frame.tsx +++ b/src/components/Frame.tsx @@ -3,7 +3,8 @@ * 职责:应用最外层,图名栏 + 图层导航 + 图例条 + 状态行 + 会签栏的容器。 * 结构:双线边框(外 1px --w + 内缩 5px 一道 --wdim)+ 42px 网格底纹(仅 canvas 区) * - * UI-1a:状态行内容为占位硬编码("● TTS 已连接 / 2 死链 · 3 待签"),UI-1b 接入真实数据。 + * UI-1b:状态行去硬编码,改由 props 驱动(connected / version / deadLinks / pending), + * 圆点色按状态色纪律(§2.5):青=已连接、红=未连接;statusLeft / statusRight 仍可整体覆写。 */ import React from "react"; import "./Frame.css"; @@ -18,9 +19,17 @@ export interface FrameProps { children?: React.ReactNode; /** 会签栏(SignBlock 元素) */ signBlock?: React.ReactNode; - /** 状态行左侧文本(UI-1b 将传入真实 hub 状态) */ + /** TTS 连接状态(/v1/status → tts.connected),缺省 false */ + connected?: boolean; + /** 连接态附注版本(/v1/status → tts.version) */ + version?: string; + /** 死链数(UI-3 素材体检回填;缺省不显示该段) */ + deadLinks?: number; + /** 待签数(UI-4 会签回填;缺省不显示该段) */ + pending?: number; + /** 状态行左侧整体覆写(缺省按 connected / version 生成) */ statusLeft?: React.ReactNode; - /** 状态行右侧文本 */ + /** 状态行右侧整体覆写(缺省按 deadLinks / pending 生成) */ statusRight?: React.ReactNode; } @@ -31,14 +40,26 @@ export default function Frame(props: FrameProps) { legend, children, signBlock, - statusLeft = ( - <> - ● TTS 已连接 - - ), - statusRight = "2 死链 · 3 待签", + connected = false, + version, + deadLinks, + pending, + statusLeft, + statusRight, } = props; + const rightParts: string[] = []; + if (deadLinks !== undefined) rightParts.push(`${deadLinks} 死链`); + if (pending !== undefined) rightParts.push(`${pending} 待签`); + const defaultStatusLeft = ( + <> + ● + {connected ? `TTS 已连接${version ? ` · ${version}` : ""}` : "TTS 未连接"} + + ); + const defaultStatusRight = + rightParts.length > 0 ? rightParts.join(" · ") : "—"; + return (
@@ -64,8 +85,12 @@ export default function Frame(props: FrameProps) { {/* 状态行(左下) */}
- {statusLeft} - {statusRight} + + {statusLeft ?? defaultStatusLeft} + + + {statusRight ?? defaultStatusRight} +
{/* 会签栏(右下常驻) */} diff --git a/src/components/HubLauncher.css b/src/components/HubLauncher.css new file mode 100644 index 0000000..3cea463 --- /dev/null +++ b/src/components/HubLauncher.css @@ -0,0 +1,150 @@ +/* — UI-1b(施工方案 v0.8.0 §8.2 方案 C 引导对话框) + * tokens:var(--bp-d) 面板底 + var(--w) 边框 + var(--amber) 警示;直角、无投影 */ + +.hublauncher { + width: 100vw; + height: 100vh; + display: flex; + align-items: center; + justify-content: center; + background: var(--bp-dd); +} + +.hublauncher-panel { + width: 520px; + max-width: calc(100vw - var(--sp-6) * 2); + background: var(--bp-d); + border: var(--border-w) solid var(--w); + border-radius: var(--radius-max); + padding: var(--sp-5); + color: var(--w); + font-family: var(--sans); + font-size: var(--fs-body); + line-height: var(--lh-body); +} + +/* 标题:琥珀方框标(等待人审语义,§2.5) */ +.hublauncher-head { + display: flex; + align-items: center; + gap: var(--sp-2); + margin-bottom: var(--sp-3); + padding-bottom: var(--sp-2); + border-bottom: var(--border-w) solid var(--wfaint); +} + +.hublauncher-marker { + width: 12px; + height: 12px; + background: var(--amber); + border-radius: var(--radius-max); + flex-shrink: 0; +} + +.hublauncher-title { + margin: 0; + font-family: var(--fs); + font-size: var(--fs-body); + font-weight: 600; + color: var(--w); + letter-spacing: 1px; +} + +/* 标注文字(仿宋层) */ +.hublauncher-note { + margin: 0 0 var(--sp-3); + font-family: var(--fs); + font-size: var(--fs-note); + color: var(--w); +} + +.hublauncher-note--dim { + color: var(--wdim); +} + +.hublauncher-warn { + margin: 0 0 var(--sp-3); + font-family: var(--fs); + font-size: var(--fs-body); + font-weight: 600; + color: var(--amber); /* 警示 = 琥珀(§2.5) */ + letter-spacing: 1px; +} + +/* 步骤:仿宋标注 + 等宽命令行 */ +.hublauncher-step { + margin-bottom: var(--sp-3); +} + +.hublauncher-step-note { + font-family: var(--fs); + font-size: var(--fs-note); + color: var(--wdim); + margin-bottom: var(--sp-1); +} + +.hublauncher-cmd { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--sp-2); + padding: var(--sp-2) var(--sp-3); + background: var(--bp-dd); + border: var(--border-w) solid var(--wfaint); + border-radius: var(--radius-max); +} + +.hublauncher-cmd-text { + font-family: var(--mono); + font-size: var(--fs-data); + line-height: var(--lh-data); + color: var(--w); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + user-select: text; /* 命令可手选复制 */ +} + +.hublauncher-cmd-copy { + flex-shrink: 0; + padding: 2px var(--sp-2); + border: var(--border-w) solid var(--wdim); + border-radius: var(--radius-max); + color: var(--w); + font-family: var(--fs); + font-size: var(--fs-note); + letter-spacing: 0.5px; + transition: + background var(--dur-fast) var(--ease-out), + border-color var(--dur-fast) var(--ease-out); +} + +.hublauncher-cmd-copy:hover { + border-color: var(--w); + background: var(--wfaint); +} + +/* 底部动作区 */ +.hublauncher-act { + display: flex; + justify-content: flex-end; + margin-top: var(--sp-4); +} + +.hublauncher-btn { + padding: var(--sp-2) var(--sp-4); + border: var(--border-w) solid var(--w); + border-radius: var(--radius-max); + background: transparent; + color: var(--w); + font-family: var(--fs); + font-size: var(--fs-note); + letter-spacing: 1px; + transition: + background var(--dur-fast) var(--ease-out), + filter var(--dur-fast) var(--ease-out); +} + +.hublauncher-btn:hover:not(:disabled) { + background: var(--wfaint); +} diff --git a/src/components/HubLauncher.tsx b/src/components/HubLauncher.tsx new file mode 100644 index 0000000..a152134 --- /dev/null +++ b/src/components/HubLauncher.tsx @@ -0,0 +1,187 @@ +/** + * hub 未启动引导 — UI-1b,施工方案 v0.8.0 §8.2 方案 C + §8.3 + * + * 状态机: + * 1. checking → Tauri invoke('check_hub') TCP 探测 39995(非 Tauri 环境<纯浏览器 dev>退化为 + * 直接 fetch /v1/status,1500ms) + * 2. 端口通 → client.status() → capabilitiesFromStatus() → + * isSupported ? onReady(caps) : 「版本过旧」面板(<0.7.0 或无 version 字段) + * 3. 端口不通 → 引导对话框:安装命令 + 启动命令(各带一键复制)+「我已启动,重试」 + * + * 样式:tokens.css——var(--bp-d) 面板底 + var(--w) 边框 + var(--amber) 警示(§2.5)。 + */ +import { useCallback, useEffect, useState } from "react"; +import { invoke } from "@tauri-apps/api/core"; +import { HUB_BASE_URL } from "../hub/client"; +import { hubClient } from "../hub/HubContext"; +import { capabilitiesFromStatus } from "../hub/capabilities"; +import type { HubCapabilities } from "../hub/capabilities"; +import "./HubLauncher.css"; + +const HUB_PORT = 39995; +const PROBE_TIMEOUT_MS = 1500; +const INSTALL_CMD = "npm install -g @smirk1921/tts-toolkit"; +const START_CMD = "tts-hub"; + +type Phase = "checking" | "guide" | "unsupported"; + +export interface HubLauncherProps { + /** 验证通过(hub 在线且版本 >= 0.7.0)后回传能力表 */ + onReady: (caps: HubCapabilities) => void; +} + +export default function HubLauncher({ onReady }: HubLauncherProps) { + const [phase, setPhase] = useState("checking"); + const [detected, setDetected] = useState(""); + const [busy, setBusy] = useState(false); + + const check = useCallback(async () => { + setBusy(true); + try { + if (!(await probePort())) { + setPhase("guide"); + return; + } + const caps = capabilitiesFromStatus(await hubClient.status()); + if (!caps.isSupported) { + setDetected(caps.version === "" ? "(无版本号,视为 0.7.0 之前)" : caps.version); + setPhase("unsupported"); + return; + } + onReady(caps); + } catch { + // 端口通但 /v1/status 失败:等同不可用,回到引导 + setPhase("guide"); + } finally { + setBusy(false); + } + }, [onReady]); + + useEffect(() => { + void check(); + }, [check]); + + return ( +
+
+ {phase === "checking" && ( +

+ 正在检测 tts-hub(127.0.0.1:{HUB_PORT})… +

+ )} + + {phase === "guide" && ( + <> +
+ +

未检测到 tts-hub

+
+

+ 桌面应用经 hub({HUB_BASE_URL.replace(/^http:\/\//, "")})与 + Tabletop Simulator 通信。请在终端先启动: +

+ + +

+ 保持该终端窗口开启,回到本应用点击重试。 +

+
+ +
+ + )} + + {phase === "unsupported" && ( + <> +

⚠ hub 版本过旧

+

+ 检测到 tts-hub {detected};本应用需要 0.7.0+(卡面预览 / 工作台保存需 + 0.8.0+)。请升级后重试: +

+ +
+ +
+ + )} +
+
+ ); +} + +/** Tauri 内走 Rust TCP 探测(check_hub);纯浏览器 dev 退化为 fetch /v1/status */ +async function probePort(): Promise { + try { + return await invoke("check_hub", { + port: HUB_PORT, + timeoutMs: PROBE_TIMEOUT_MS, + }); + } catch { + return probeHttp(); + } +} + +async function probeHttp(): Promise { + const ctrl = new AbortController(); + const timer = setTimeout(() => ctrl.abort(), PROBE_TIMEOUT_MS); + try { + const res = await fetch(`${HUB_BASE_URL}/v1/status`, { + signal: ctrl.signal, + }); + return res.ok; + } catch { + return false; + } finally { + clearTimeout(timer); + } +} + +/** 命令行 + 一键复制(仿宋标注 + 等宽命令) */ +function CopyRow({ label, cmd }: { label: string; cmd: string }) { + const [copied, setCopied] = useState(false); + const copy = async () => { + try { + await navigator.clipboard.writeText(cmd); + setCopied(true); + window.setTimeout(() => setCopied(false), 1500); + } catch { + /* 剪贴板不可用时静默:命令文本仍可见 */ + } + }; + return ( +
+
{label}
+
+ {cmd} + +
+
+ ); +} diff --git a/src/components/LayerNav.tsx b/src/components/LayerNav.tsx index d881b6e..48c3b8d 100644 --- a/src/components/LayerNav.tsx +++ b/src/components/LayerNav.tsx @@ -4,7 +4,8 @@ * 结构:圆圈序号 + 名称 + 状态圆点(7px,红=有问题 / 蓝=活动 / 青=正常) * 状态:.on = 白底蓝字反色 * - * UI-1a:状态圆点色为演示硬编码(五面 demo 各取一色),UI-1b 改为按 hubCapabilities 真实计算。 + * UI-1b:圆点仍由外部经 items[].dot 传入(本组件不持状态);真实状态色由 UI-2/3/4 + * 按各工作面数据计算后经 App 下发,本文件无需改动。 */ import "./LayerNav.css"; diff --git a/src/hub/HubContext.ts b/src/hub/HubContext.ts new file mode 100644 index 0000000..3292cb0 --- /dev/null +++ b/src/hub/HubContext.ts @@ -0,0 +1,30 @@ +/** + * HubContext — UI-1b 全站 hub 状态下发(施工方案 v0.8.0 §8.5-4) + * + * App 在 HubLauncher 验证通过后,把 caps 与 client 单例经 Provider 下发; + * 路由组件(①代码 / ③卡牌 / ④素材…)经 useHub() 消费, + * 依赖新路由的功能按 caps.canReadFiles / caps.canWriteFiles 禁用 + 提示。 + */ +import { createContext, useContext } from "react"; +import { HubClient } from "./client"; +import type { HubCapabilities } from "./capabilities"; + +/** 全站 client 单例(HubLauncher 探测与各路由共用同一实例) */ +export const hubClient = new HubClient(); + +export interface HubContextValue { + client: HubClient; + caps: HubCapabilities; +} + +export const HubContext = createContext(null); + +export function useHub(): HubContextValue { + const v = useContext(HubContext); + if (v === null) { + throw new Error( + "useHub() 必须在 内使用(caps 未就绪时应渲染 HubLauncher)", + ); + } + return v; +} diff --git a/src/hub/capabilities.ts b/src/hub/capabilities.ts new file mode 100644 index 0000000..f159f41 --- /dev/null +++ b/src/hub/capabilities.ts @@ -0,0 +1,61 @@ +/** + * hub 版本兼容策略 — UI-1b,施工方案 v0.8.0 §8.3(审批意见 §4) + * + * UI 启动查 GET /v1/status,按 hub.version 决定功能可用性: + * - < 0.7.0(含无 version 字段的旧版):isSupported=false → 拒绝接入,HubLauncher 提示升级 + * - 0.7.0:降级模式(基础面可用,卡面预览 / 工作台保存禁用) + * - >= 0.8.0:全功能(canReadFiles / canWriteFiles) + * MINOR bump 向前兼容:旧 UI 连新 hub 正常;新 UI 必须能识别哪些路由可用。 + */ +import type { HubStatus } from "./client"; + +export type HubAppMode = "standalone" | "app"; + +export type HubCapabilities = { + version: string; + appMode: HubAppMode; + /** POST /v1/files/read(version >= 0.8.0) */ + canReadFiles: boolean; + /** PUT /v1/files/write(version >= 0.8.0) */ + canWriteFiles: boolean; + /** version >= 0.7.0(无 version 字段视为 0.7.0 之前,拒绝接入) */ + isSupported: boolean; +}; + +const MIN_SUPPORTED = "0.7.0"; +const FILES_SINCE = "0.8.0"; + +/** 简易 semver 比较:按 "." 切前三段逐段数值比较;非数值段记 0。ab → 1 */ +export function compareSemver(a: string, b: string): number { + const seg = (v: string): [number, number, number] => { + const parts = v.split(".").map((s) => { + const n = Number.parseInt(s, 10); + return Number.isFinite(n) ? n : 0; + }); + return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0]; + }; + const pa = seg(a); + const pb = seg(b); + for (let i = 0; i < 3; i++) { + if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1; + } + return 0; +} + +/** 由 /v1/status 响应推导能力表;响应缺 hub 字段(旧版)时全部降级 */ +export function capabilitiesFromStatus(status: HubStatus): HubCapabilities { + const hub = (status as { hub?: { version?: unknown; appMode?: unknown } }) + ?.hub; + const version = + typeof hub?.version === "string" ? hub.version : ""; + const appMode: HubAppMode = hub?.appMode === "app" ? "app" : "standalone"; + const supported = version !== "" && compareSemver(version, MIN_SUPPORTED) >= 0; + const files = version !== "" && compareSemver(version, FILES_SINCE) >= 0; + return { + version, + appMode, + canReadFiles: files, + canWriteFiles: files, + isSupported: supported, + }; +} diff --git a/src/hub/client.ts b/src/hub/client.ts new file mode 100644 index 0000000..97d35b7 --- /dev/null +++ b/src/hub/client.ts @@ -0,0 +1,321 @@ +/** + * HubClient(fetch 版)— UI-1b,施工方案 v0.8.0 §8.5-2 + * + * 覆盖控制通道全部 16 条 JSON 路由(14 条既有 + /v1/files/read + /v1/files/write, + * 契约:tts-toolkit/docs/schemas/hub-control.md §4 + v0.8.0 §8.4;接口签名见本窗口任务书)。 + * SSE 不在本类(见 ./sse.ts)——与 tts-toolkit 的 HubClient(src/mcp/client.ts)同构但面向浏览器。 + * + * 错误约定:所有方法只抛 HubError(./errors.ts)。 + * - fetch reject / AbortController 超时 / 响应体读取中断 → NETWORK_ERROR(无 httpStatus) + * - 非 2xx 且 body 为 {error:{code,message,details?}} → 透传服务端 code / httpStatus / details + * (details.userAction 提升为 userAction,appMode==="app" 时 hub 下发) + * - 其余(非 2xx body 非标准错误形 / 2xx body 非法 JSON)→ PARSE_ERROR + * + * 超时:fetch + AbortController,默认 10s;exec 缺省 30s(Lua timeoutMs 更大时取其 + 5s 余量)。 + */ +import { HubError } from "./errors"; + +/** 控制通道缺省地址(只绑回环,契约 §8) */ +export const HUB_BASE_URL = "http://127.0.0.1:39995"; +/** 单请求缺省超时(发起请求 + 读取响应体全程) */ +export const DEFAULT_TIMEOUT_MS = 10_000; + +/** GET /v1/status 响应(hub.version / hub.appMode 为 v0.8.0 新增字段) */ +export interface HubStatus { + ok: boolean; + hub: { + editor: number; + tcpClients: number; + wsClients: number; + inprocClients: number; + startedAt: number; + uptimeMs: number; + version: string; + appMode: "standalone" | "app"; + }; + tts: { connected: boolean; version?: string; objects?: number }; +} + +/** {ok:true} 通用成功形(save-and-play / shutdown) */ +export interface HubOk { + ok: true; +} + +export interface ScriptState { + name: string; + guid: string; + script?: string; + ui?: string; +} + +export interface ExecOptions { + guid?: string; + timeoutMs?: number; +} + +export interface PushOptions { + dryRun?: boolean; + forceScriptsOnly?: boolean; + skipBackup?: boolean; + skipBaselineCheck?: boolean; + backupRetention?: number; +} + +export interface TestRunOptions { + root: string; + targetGuid?: string; + timeoutMs?: number; + bail?: boolean; + bundle?: boolean; + include?: string[]; +} + +export interface PackBuildOptions { + root: string; + outPath?: string; + dryRun?: boolean; +} + +export interface SliceOptions { + sheetPath: string; + savePath: string; + outDir: string; + deckKey?: string; + deckGuid?: string; +} + +export interface ReplaceRule { + from: string; + to: string; + mode?: "exact" | "regex" | "prefix"; +} + +export interface PlanOptions { + savePath: string | Record; + rules: ReplaceRule[]; +} + +/** POST /v1/files/read 成功响应 */ +export interface FilesReadResult { + base64: string; + mime: string; + size: number; +} + +/** PUT /v1/files/write 成功响应 */ +export interface FilesWriteResult { + sha256: string; + size: number; +} + +interface ErrorBody { + error?: { code?: unknown; message?: unknown; details?: unknown }; +} + +export class HubClient { + private readonly baseUrl: string; + + constructor(baseUrl: string = HUB_BASE_URL) { + this.baseUrl = baseUrl.replace(/\/+$/, ""); + } + + // ---- GET ---- + + status(): Promise { + return this.request("GET", "/v1/status"); + } + + packs(packsRoot?: string): Promise { + return this.request("GET", "/v1/packs", { + query: packsRoot ? { packsRoot } : undefined, + }); + } + + // ---- POST ---- + + pullScripts(root: string): Promise { + return this.request("POST", "/v1/scripts/pull", { body: { root } }); + } + + saveAndPlay(scriptStates: ScriptState[]): Promise { + return this.request("POST", "/v1/scripts/save-and-play", { + body: { scriptStates }, + }); + } + + exec(lua: string, opts?: ExecOptions): Promise { + return this.request("POST", "/v1/exec", { + body: { lua, ...(opts ?? {}) }, + // Lua 可能长时间执行:HTTP 超时缺省 30s,随 timeoutMs 放宽 +5s 余量 + timeoutMs: Math.max(30_000, (opts?.timeoutMs ?? 0) + 5_000), + }); + } + + assetsCheck(urls: string[], timeoutMs?: number): Promise { + return this.request("POST", "/v1/assets/check", { + body: { urls, timeoutMs }, + }); + } + + deckSlice(opts: SliceOptions): Promise { + return this.request("POST", "/v1/deck/slice", { body: opts }); + } + + deckPlan(opts: PlanOptions): Promise { + return this.request("POST", "/v1/deck/plan", { body: opts }); + } + + importAssets( + root: string, + manifestPath: string, + dryRun?: boolean, + ): Promise { + return this.request("POST", "/v1/import", { + body: { root, manifestPath, dryRun }, + }); + } + + diff(root: string): Promise { + return this.request("POST", "/v1/diff", { body: { root } }); + } + + push(root: string, confirm: true, opts?: PushOptions): Promise { + return this.request("POST", "/v1/push", { + body: { root, confirm, ...(opts ?? {}) }, + }); + } + + testRun(opts: TestRunOptions): Promise { + return this.request("POST", "/v1/test/run", { body: opts }); + } + + packBuild(opts: PackBuildOptions): Promise { + return this.request("POST", "/v1/pack/build", { body: opts }); + } + + shutdown(): Promise { + return this.request("POST", "/v1/hub/shutdown"); + } + + /** v0.8.0 新增:读 root 内本地文件(≤20MB,防路径穿越)——UI 专用,不加 MCP 工具 */ + filesRead(root: string, path: string): Promise { + return this.request("POST", "/v1/files/read", { body: { root, path } }); + } + + /** v0.8.0 新增:写 root 内文本文件(≤1MB,baseSha256 乐观锁,不符 409 HUB_CONFLICT) */ + filesWrite( + root: string, + path: string, + content: string, + baseSha256?: string, + ): Promise { + return this.request("PUT", "/v1/files/write", { + body: { root, path, content, baseSha256 }, + }); + } + + // ---- 内部 ---- + + private async request( + method: "GET" | "POST" | "PUT", + path: string, + init?: { body?: unknown; timeoutMs?: number; query?: Record }, + ): Promise { + const timeoutMs = init?.timeoutMs ?? DEFAULT_TIMEOUT_MS; + const url = new URL(path, `${this.baseUrl}/`); + for (const [k, v] of Object.entries(init?.query ?? {})) { + url.searchParams.set(k, v); + } + + const ctrl = new AbortController(); + const timer = setTimeout(() => ctrl.abort(), timeoutMs); + let res: Response; + try { + res = await fetch(url, { + method, + headers: + init?.body === undefined + ? undefined + : { "Content-Type": "application/json" }, + body: init?.body === undefined ? undefined : JSON.stringify(init.body), + signal: ctrl.signal, + }); + } catch (e) { + const cause = e instanceof Error ? e.message : String(e); + throw new HubError({ + code: "NETWORK_ERROR", + message: ctrl.signal.aborted + ? `hub 请求超时(${timeoutMs}ms):${url.pathname}` + : `无法连接 hub(${cause})`, + details: cause, + }); + } finally { + clearTimeout(timer); + } + + let text: string; + try { + text = await res.text(); + } catch (e) { + const cause = e instanceof Error ? e.message : String(e); + throw new HubError({ + code: "NETWORK_ERROR", + message: `hub 响应体读取中断:${cause}`, + }); + } + + if (!res.ok) { + const body = safeParse(text) as ErrorBody | null; + const err = + body !== null && typeof body === "object" ? body.error : undefined; + if ( + err !== undefined && + typeof err === "object" && + typeof (err as { code?: unknown }).code === "string" + ) { + const details = (err as { details?: unknown }).details; + throw new HubError({ + code: (err as { code: string }).code, + message: + typeof (err as { message?: unknown }).message === "string" + ? (err as { message: string }).message + : `HTTP ${res.status}`, + httpStatus: res.status, + userAction: pickUserAction(details), + details, + }); + } + throw new HubError({ + code: "PARSE_ERROR", + message: `HTTP ${res.status}:响应体不是标准错误格式`, + httpStatus: res.status, + details: text.slice(0, 500), + }); + } + + const parsed = safeParse(text); + if (parsed === null) { + throw new HubError({ + code: "PARSE_ERROR", + message: `HTTP ${res.status}:响应体不是合法 JSON`, + httpStatus: res.status, + details: text.slice(0, 500), + }); + } + return parsed as T; + } +} + +function safeParse(text: string): unknown { + try { + return JSON.parse(text) as unknown; + } catch { + return null; + } +} + +function pickUserAction(details: unknown): string | undefined { + if (details === null || typeof details !== "object") return undefined; + const ua = (details as { userAction?: unknown }).userAction; + return typeof ua === "string" ? ua : undefined; +} diff --git a/src/hub/errors.ts b/src/hub/errors.ts new file mode 100644 index 0000000..c3aecc9 --- /dev/null +++ b/src/hub/errors.ts @@ -0,0 +1,43 @@ +/** + * HubError — UI-1b 唯一错误类型(施工方案 v0.8.0 §8.5-3,审批意见 §8) + * + * 约定:UI 组件只 catch 这一种。hub 侧错误(4xx/5xx 响应体 {error:{code,message,details?}}) + * 原样透传 code / httpStatus / details;网络层失败统一归 NETWORK_ERROR;响应体不合规归 PARSE_ERROR。 + * + * code 取值(非封闭联合:服务端新码透传不截断): + * - 服务端:HUB_BAD_REQUEST / HUB_CONFLICT / HUB_PATH_ESCAPE / HUB_FILE_TOO_LARGE / + * HUB_NOT_FOUND / HUB_METHOD_NOT_ALLOWED / HUB_PAYLOAD_TOO_LARGE / + * HUB_UNSUPPORTED_MEDIA_TYPE / HUB_CONFIRM_REQUIRED / HUB_PACK_ERROR / + * HUB_LUA_ERROR / HUB_INTERNAL_ERROR / ... + * - 客户端:NETWORK_ERROR(fetch reject / 超时中止 / 响应体读取中断)、PARSE_ERROR(响应体不合规) + */ +export class HubError extends Error { + /** 机器可读错误码(服务端透传或客户端分类,见模块头注释) */ + readonly code: string; + /** HTTP 状态码;网络层失败(NETWORK_ERROR)时缺省 */ + readonly httpStatus?: number; + /** appMode === "app" 时 hub 随 details.userAction 下发的用户可操作提示 */ + readonly userAction?: string; + /** 错误细节(hub 的 details 原样;客户端补充时为 string 摘要) */ + readonly details?: unknown; + + constructor(init: { + code: string; + message: string; + httpStatus?: number; + userAction?: string; + details?: unknown; + }) { + super(init.message); + this.name = "HubError"; + this.code = init.code; + this.httpStatus = init.httpStatus; + this.userAction = init.userAction; + this.details = init.details; + } +} + +/** 类型守卫:UI 组件 `catch (e) { if (isHubError(e)) ... }` */ +export function isHubError(e: unknown): e is HubError { + return e instanceof HubError; +} diff --git a/src/hub/sse.ts b/src/hub/sse.ts new file mode 100644 index 0000000..861e7af --- /dev/null +++ b/src/hub/sse.ts @@ -0,0 +1,115 @@ +/** + * SSE 订阅 — UI-1b,施工方案 v0.8.0 §8.5-2(GET /v1/events,契约 hub-control.md §5) + * + * 浏览器原生 EventSource:自动重连(含服务端重启后回连),状态经 onStateChange 上报。 + * data 帧为 TTS 入站消息原样 JSON(messageID 转发集合:1 GameLoaded / 2 Print / 3 Error / + * 4 CustomMessage / 6 GameSaved / 7 ObjectCreated;无 id:/event:/心跳/回放)。 + * + * 用法: + * const stop = subscribeEvents("http://127.0.0.1:39995", onEvent, onStateChange); + * ... // 组件卸载时 + * stop(); // 关闭连接并上报 "closed" + */ + +export type HubEventType = + | "loaded" // messageID 1 GameLoaded + | "print" // 2 Print + | "error" // 3 Error + | "object" // 7 ObjectCreated + | "saved" // 6 GameSaved + | "unknown"; // 4 CustomMessage / 无法分类 + +export interface HubEvent { + type: HubEventType; + /** 本地接收时刻(epoch ms) */ + ts: number; + /** 人类可读摘要(中文,供事件流面板直显) */ + msg: string; + /** 解析后的原始消息对象(data 非法 JSON 时为原始文本) */ + raw: unknown; +} + +export type HubStreamState = "connecting" | "open" | "closed"; + +export function subscribeEvents( + baseUrl: string, + onEvent: (e: HubEvent) => void, + onStateChange: (s: HubStreamState) => void, +): () => void { + const url = `${baseUrl.replace(/\/+$/, "")}/v1/events`; + const es = new EventSource(url); + + es.onopen = () => onStateChange("open"); + // onerror 后 readyState 仍为 CONNECTING = EventSource 在自动重连;CLOSED = 彻底失败 + es.onerror = () => + onStateChange( + es.readyState === EventSource.CLOSED ? "closed" : "connecting", + ); + + es.onmessage = (ev: MessageEvent) => { + let raw: unknown = ev.data; + try { + raw = JSON.parse(ev.data) as unknown; + } catch { + /* 保持原始文本,分类为 unknown */ + } + onEvent({ type: classify(raw), ts: Date.now(), msg: describe(raw), raw }); + }; + + return () => { + es.close(); + onStateChange("closed"); + }; +} + +function classify(raw: unknown): HubEventType { + const id = messageID(raw); + switch (id) { + case 1: + return "loaded"; + case 2: + return "print"; + case 3: + return "error"; + case 6: + return "saved"; + case 7: + return "object"; + default: + return "unknown"; + } +} + +function messageID(raw: unknown): number | undefined { + if (typeof raw !== "object" || raw === null) return undefined; + const id = (raw as { messageID?: unknown }).messageID; + return typeof id === "number" ? id : undefined; +} + +function describe(raw: unknown): string { + if (typeof raw !== "object" || raw === null) return String(raw ?? ""); + const r = raw as Record; + switch (messageID(raw)) { + case 1: { + const n = Array.isArray(r.scriptStates) ? r.scriptStates.length : 0; + return `GameLoaded(${n} 个脚本状态)`; + } + case 2: + return `Print:${String(r.message ?? "")}`; + case 3: { + const at = r.guid != null ? ` @${String(r.guid)}` : ""; + const what = String(r.errorMessagePrefix ?? r.error ?? ""); + return `TTS Error${at}:${what}`; + } + case 6: + return typeof r.savePath === "string" + ? `GameSaved:${r.savePath}` + : "GameSaved"; + case 7: + return `ObjectCreated ${String(r.guid ?? "")}`; + case 4: + return "CustomMessage"; + default: + return `messageID ${String(r.messageID ?? "?")}`; + } +}