From d2646f534e308e43a49f7bd7801e026fa0fef48d Mon Sep 17 00:00:00 2001 From: kyugao Date: Mon, 3 Aug 2026 12:58:01 +0800 Subject: [PATCH] feat: establish typed runtime protocol model --- README.md | 21 +-- tauri/README.md | 19 ++- tauri/package.json | 2 +- tauri/src/main.ts | 27 +++- tauri/src/protocol.ts | 301 ++++++++++++++++++++++++++++++++++++++---- 5 files changed, 325 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 366c236..fe1a280 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,22 @@ 当前 Kotlin Android 客户端是 IM、协议、设备接入与交互闭环的快速实验基线；长期目标是在系统 WebView / WebKit 之上构建 LineUp Mini Runtime，为内置 Renderer 与受限第三方小程序 Surface 提供统一的运行环境。 -## Git 同步约定 +## Git 与开发验证约定 -客户端工作区使用独立仓库，远端为 `ssh://git@100.121.118.116:2222/lineup/app.git`，`main` 是 Linux 与 macOS 唯一的共享同步分支。每个可验证的客户端改动都应提交并推送到 `origin/main`；不要再通过复制 `node_modules`、`target` 或打包产物在开发机间同步。 +客户端工作区使用独立仓库，远端为 `ssh://git@100.121.118.116:2222/lineup/app.git`。Git 用于源码版本管理、备份和协作；提交应对应完整、可验证的改动，但**不再作为 Mac 浏览器验证前端改动的传输手段**。 -macOS 首次获取： +日常 Web 联调由 Linux 工作机直接提供可信 Host： + +```bash +cd lineup-app/tauri +npm run web:dev +``` + +Mac 浏览器通过 Tailscale 打开 `http://100.121.118.116:1420`，即可看到 Linux 工作区的 Vite 热更新。Mac 只在首次配置、切换开发机或需要本地桌面打包时再 clone / pull 源码： ```bash git clone ssh://git@100.121.118.116:2222/lineup/app.git ~/Workspace/lineup-app -cd ~/Workspace/lineup-app/tauri -npm ci -``` - -日常同步（工作区无未提交源码改动时）： - -```bash +cd ~/Workspace/lineup-app git pull --ff-only origin main ``` diff --git a/tauri/README.md b/tauri/README.md index d6b0e2a..cef0b87 100644 --- a/tauri/README.md +++ b/tauri/README.md @@ -35,7 +35,7 @@ macOS 的 `src-tauri/Info.plist` 为当前 Tailscale / 私网 HTTP AppServer 配 ### M0 回归场景 -每次迁移或拆分模块后，至少执行以下场景；其中 `R01` 为构建级检查，其余为 Mac 浏览器开发态人工验收，直至 M0 建立自动化测试。 +每次迁移或拆分模块后，至少执行以下场景；其中 `R01` 为构建级检查，其余为 Mac 浏览器访问 Linux 开发 Host 的人工验收，直至 M0 建立自动化测试。 - **M0-R01：构建。** `npm run build` 通过 TypeScript 检查与 Vite 打包。 - **M0-R02：登录。** 使用 Tailscale AppServer 登录；成功切换到聊天页，错误地址/超时给出可理解提示。 @@ -49,6 +49,16 @@ macOS 的 `src-tauri/Info.plist` 为当前 Tailscale / 私网 HTTP AppServer 配 `src/main.ts` 目前同时包含 App Shell、页面 DOM、登录、直接 HTTP `fetch`、会话 cursor、同步循环、协议到展示的映射和 renderer。M0 的目的不是改变上述用户行为，而是将它们迁入 `app-shell`、`transport`、`conversation-store`、`interaction-kernel` 和 `renderer-registry` 等独立边界；在 M0 准入前不新增 Surface 或 Capability 功能。 +### M0-02 协议模型（已完成） + +`src/protocol.ts` 是目前唯一允许把 Transport 原始 payload 转换成可信表现模型的入口。它定义了 `JsonValue`、`Actor`、严格 `Envelope`、`ConversationItem`、`UserAction`、`DeliveryState` 与 `ProtocolFallback`，并提供： + +- `parseEnvelope(value)`：校验版本、消息类型、`id`、`conversation_id`、sender/target、timestamp 和 JSON payload； +- `parseEnvelopeJSON(raw)`：供不接受历史纯文本的 Transport / Kernel 路径把非法 JSON 明确归为 `invalid_json`； +- `decodeConversationItem(raw)`：保留历史纯文本作为 Markdown 的兼容行为；对于非法 LineUp envelope、未知类型和各类非法 payload，返回受控 fallback，绝不触发执行。 + +该文件不依赖 DOM、`fetch`、Tauri 或本地存储。Surface 与 Capability 在本阶段只校验其基础合约并降级显示；不加载 bundle，也不调用能力。下一项 M0-03 才会将此模型接入 Interaction Kernel 和 Renderer Registry。 + ## 本地命令 ```bash @@ -58,9 +68,12 @@ npm install # 日常开发：启动 Vite 热更新 + 未打包的 Tauri 桌面壳 npm run desktop:dev -# 纯 Web 开发：仅启动 Vite，在浏览器打开 http://127.0.0.1:1420 +# 纯 Web 开发：Linux 开发机监听全部网卡，供 Mac 浏览器访问 npm run web:dev +# Mac 浏览器访问（经 Tailscale） +# http://100.121.118.116:1420 + # 仅检查并构建前端静态文件 npm run build @@ -73,7 +86,7 @@ npm run tauri build -- --debug `npm run desktop:dev` 不生成 `.app`、`.dmg` 或安装包。前端 TypeScript / CSS / HTML 保存后会由 Vite 自动热更新；改动 `src-tauri/` 中的 Rust Host 代码时，Tauri 会重新编译并重启开发窗口。只有需要交付可安装文件时才执行 `tauri build`。 -`npm run web:dev` 只运行同一份可信 Host Web UI，适合在浏览器中快速调试登录、消息和 Renderer。它不具备 Tauri 原生能力，也不应作为第三方 Mini Runtime Surface 的安全验收环境。AppServer 已对固定开发 Origin `http://127.0.0.1:1420` 配置 CORS；若改动 Vite 端口或 host，必须同步收紧更新 AppServer 的 `client.allowedOrigins`。 +`npm run web:dev` 只运行同一份可信 Host Web UI，适合在浏览器中快速调试登录、消息和 Renderer。它监听 `0.0.0.0:1420`，Mac 通过 Tailscale 打开 `http://100.121.118.116:1420`，直接验证 Linux 工作区的 Vite 热更新；不需要为每次验证将源码同步到 Mac。它不具备 Tauri 原生能力，也不应作为第三方 Mini Runtime Surface 的安全验收环境。AppServer 仅对固定开发 Origin `http://127.0.0.1:1420` 和 `http://100.121.118.116:1420` 配置 CORS；若改动 Vite 端口或 Host 地址，必须同步收紧更新 AppServer 的 `client.allowedOrigins`，不得改为 wildcard。 本项目的 `tauri` 与 `check:rust` npm 脚本会自动识别 Linux x86_64、macOS Apple Silicon、macOS Intel 的 Rust stable toolchain，并加入 `PATH`。因此不要直接执行裸 `tauri build`；统一使用 `npm run tauri build -- --debug`。如 Rust toolchain 安装在其他位置，可临时覆盖： diff --git a/tauri/package.json b/tauri/package.json index 4cf9f67..9310cfc 100644 --- a/tauri/package.json +++ b/tauri/package.json @@ -4,7 +4,7 @@ "version": "0.1.0", "type": "module", "scripts": { - "dev": "vite --host 127.0.0.1 --port 1420", + "dev": "vite --host 0.0.0.0 --port 1420", "web:dev": "npm run dev", "desktop:dev": "./scripts/tauri.sh dev", "build": "tsc --noEmit && vite build", diff --git a/tauri/src/main.ts b/tauri/src/main.ts index 15176e7..118acd0 100644 --- a/tauri/src/main.ts +++ b/tauri/src/main.ts @@ -1,7 +1,13 @@ import DOMPurify from "dompurify"; import { marked } from "marked"; import "./style.css"; -import { decodeConversationItem, type ConversationItem, type Envelope } from "./protocol"; +import { + decodeConversationItem, + type Actor, + type ConversationItem, + type Envelope, + type JsonObject, +} from "./protocol"; type Session = { api: string; @@ -232,6 +238,21 @@ $("#message-form").addEventListener("submit", async event => { $("#logout").addEventListener("click", () => { session.active = false; messages.replaceChildren(); chatView.hidden = true; loginView.hidden = false; }); -export function makeProtocolEvent(type: string, payload: Record, conversationID: string): Envelope { - return { v: 1, id: `msg_${crypto.randomUUID()}`, type, conversation_id: conversationID, payload }; +export function makeProtocolEvent( + type: string, + payload: JsonObject, + conversationID: string, + sender: Actor, + target?: Actor, +): Envelope { + return { + v: 1, + id: `msg_${crypto.randomUUID()}`, + type, + conversation_id: conversationID, + sender, + ...(target ? { target } : {}), + timestamp: new Date().toISOString(), + payload, + }; } diff --git a/tauri/src/protocol.ts b/tauri/src/protocol.ts index 72a7ccd..1be8578 100644 --- a/tauri/src/protocol.ts +++ b/tauri/src/protocol.ts @@ -1,32 +1,252 @@ +/** + * Platform-neutral LineUp v1 protocol model. + * + * This module deliberately contains no DOM, network, Tauri, or storage code. + * It is the boundary between untrusted transport payloads and the trusted + * Interaction Kernel introduced in M0-03. + */ export const LINEUP_PROTOCOL_VERSION = 1; +export type JsonPrimitive = string | number | boolean | null; +export type JsonValue = JsonPrimitive | JsonObject | JsonValue[]; +export type JsonObject = { [key: string]: JsonValue }; + +export type ActorKind = "human" | "agent" | "app" | "system"; + +export type Actor = { + kind: ActorKind; + id: string; +}; + +/** A validated LineUp v1 wire envelope. */ export type Envelope = { - v: number; - id?: string; + v: typeof LINEUP_PROTOCOL_VERSION; + id: string; type: string; - conversation_id?: string; - payload?: unknown; + conversation_id: string; + sender: Actor; + target?: Actor; + /** ISO-8601 timestamp supplied by the producing adapter or client. */ + timestamp?: string; + payload: JsonObject; +}; + +export type DeliveryState = + | { status: "local_pending"; updated_at: string } + | { status: "submitted"; updated_at: string; transport_id?: string } + | { status: "delivered"; updated_at: string; transport_id?: string } + | { status: "failed"; updated_at: string; error: string; retryable: boolean }; + +/** + * A user-originated action awaiting delivery through the Transport Adapter. + * It is data only: the Store owns retries and the Kernel owns state changes. + */ +export type UserAction = + | { + kind: "send-text"; + id: string; + conversation_id: string; + text: string; + created_at: string; + delivery: DeliveryState; + } + | { + kind: "tool-result" | "tool-cancel"; + id: string; + conversation_id: string; + call_id: string; + payload: JsonObject; + created_at: string; + delivery: DeliveryState; + } + | { + kind: "surface-event"; + id: string; + conversation_id: string; + instance_id: string; + event: string; + data: JsonObject; + created_at: string; + delivery: DeliveryState; + } + | { + kind: "app-result"; + id: string; + conversation_id: string; + call_id: string; + payload: JsonObject; + created_at: string; + delivery: DeliveryState; + }; + +export type ProtocolFallbackCode = + | "invalid_json" + | "invalid_envelope" + | "unsupported_version" + | "unsupported_type" + | "invalid_payload"; + +/** Safe, displayable representation of content that must never be executed. */ +export type ProtocolFallback = { + code: ProtocolFallbackCode; + /** A stable, non-sensitive diagnostic intended for logs and the fallback renderer. */ + detail: string; + envelope?: Envelope; +}; + +type ConversationItemBase = { + id?: string; + envelope?: Envelope; }; export type ConversationItem = - | { kind: "markdown"; markdown: string; envelope?: Envelope } - | { kind: "agent-status"; status: string; detail: string; envelope?: Envelope } - | { kind: "progress"; title: string; percent: number; status: string; envelope?: Envelope } - | { kind: "error"; message: string; envelope?: Envelope } - | { kind: "surface"; envelope: Envelope } - | { kind: "app-call"; envelope: Envelope } - | { kind: "fallback"; reason: string; envelope?: Envelope }; + | (ConversationItemBase & { kind: "user-message"; text: string; delivery: DeliveryState }) + | (ConversationItemBase & { kind: "markdown"; markdown: string }) + | (ConversationItemBase & { kind: "agent-status"; status: string; detail: string }) + | (ConversationItemBase & { kind: "progress"; title: string; percent: number; status: string }) + | (ConversationItemBase & { kind: "error"; message: string; code?: string }) + | (ConversationItemBase & { kind: "surface"; envelope: Envelope }) + | (ConversationItemBase & { kind: "app-call"; envelope: Envelope }) + | (ConversationItemBase & { kind: "fallback"; reason: ProtocolFallbackCode; detail: string; envelope?: Envelope }); -function object(value: unknown): Record | null { +export type EnvelopeParseResult = + | { ok: true; envelope: Envelope } + | { ok: false; fallback: ProtocolFallback }; + +const ACTOR_KINDS = new Set(["human", "agent", "app", "system"]); +const SUPPORTED_TYPES = new Set([ + "lineup.v1.text", + "lineup.v1.agent.status", + "lineup.v1.agent.progress", + "lineup.v1.error", + "lineup.v1.ui.open", + "lineup.v1.ui.patch", + "lineup.v1.ui.close", + "lineup.v1.app.call", +]); +const ID_MAX_LENGTH = 256; +const INSTANCE_ID = /^[A-Za-z0-9._:-]{1,128}$/; +const MESSAGE_TYPE = /^lineup\.v1\.[a-z][a-z0-9.]*[a-z0-9]$/; + +function object(value: unknown): JsonObject | null { return value !== null && typeof value === "object" && !Array.isArray(value) - ? (value as Record) + ? (value as JsonObject) : null; } +function isJsonValue(value: unknown, depth = 0): value is JsonValue { + if (depth > 32 || value === null || typeof value === "string" || typeof value === "boolean") return depth <= 32; + if (typeof value === "number") return Number.isFinite(value); + if (Array.isArray(value)) return value.every(entry => isJsonValue(entry, depth + 1)); + if (value === null || typeof value !== "object") return false; + const prototype = Object.getPrototypeOf(value); + return (prototype === Object.prototype || prototype === null) + && Object.values(value).every(entry => isJsonValue(entry, depth + 1)); +} + function text(value: unknown): string { return typeof value === "string" ? value : ""; } +function identifier(value: unknown): string | null { + return typeof value === "string" && value.trim().length > 0 && value.length <= ID_MAX_LENGTH + ? value + : null; +} + +function parseActor(value: unknown): Actor | null { + const candidate = object(value); + const id = candidate && identifier(candidate.id); + const kind = candidate?.kind; + return id && typeof kind === "string" && ACTOR_KINDS.has(kind as ActorKind) + ? { kind: kind as ActorKind, id } + : null; +} + +function fallback(code: ProtocolFallbackCode, detail: string, envelope?: Envelope): EnvelopeParseResult { + return { ok: false, fallback: { code, detail, envelope } }; +} + +/** + * Validates the shared envelope shape. It intentionally does not dispatch a + * message to a renderer or execute any request; that belongs to the Kernel. + */ +export function parseEnvelope(value: unknown): EnvelopeParseResult { + const candidate = object(value); + if (!candidate) return fallback("invalid_envelope", "Envelope must be a JSON object."); + if (candidate.v !== LINEUP_PROTOCOL_VERSION) return fallback("unsupported_version", "Unsupported LineUp protocol version."); + + const id = identifier(candidate.id); + const type = text(candidate.type); + const conversationID = identifier(candidate.conversation_id); + const sender = parseActor(candidate.sender); + const payload = object(candidate.payload); + if (!id || !MESSAGE_TYPE.test(type) || !conversationID || !sender || !payload || !isJsonValue(payload)) { + return fallback("invalid_envelope", "Missing or invalid required LineUp envelope fields."); + } + + let target: Actor | undefined; + if (candidate.target !== undefined) { + target = parseActor(candidate.target) ?? undefined; + if (!target) return fallback("invalid_envelope", "Envelope target must be a valid actor."); + } + if (candidate.timestamp !== undefined && (typeof candidate.timestamp !== "string" || Number.isNaN(Date.parse(candidate.timestamp)))) { + return fallback("invalid_envelope", "Envelope timestamp must be an ISO-8601 string."); + } + + return { + ok: true, + envelope: { + v: LINEUP_PROTOCOL_VERSION, + id, + type, + conversation_id: conversationID, + sender, + ...(target ? { target } : {}), + ...(candidate.timestamp !== undefined ? { timestamp: candidate.timestamp as string } : {}), + payload, + }, + }; +} + +/** Parses a JSON wire payload when callers do not support legacy plain text. */ +export function parseEnvelopeJSON(raw: string): EnvelopeParseResult { + try { + return parseEnvelope(JSON.parse(raw)); + } catch { + return fallback("invalid_json", "Transport payload is not valid JSON."); + } +} + +function validSurfacePayload(type: string, payload: JsonObject): boolean { + const instanceID = text(payload.instance_id); + if (!INSTANCE_ID.test(instanceID)) return false; + if (type === "lineup.v1.ui.open") { + if (!object(payload.app)) return false; + return payload.state === undefined || object(payload.state) !== null; + } + if (type === "lineup.v1.ui.patch") return object(payload.state) !== null; + return type === "lineup.v1.ui.close"; +} + +function validAppCallPayload(payload: JsonObject): boolean { + return Boolean(identifier(payload.call_id) && identifier(payload.capability) && object(payload.arguments)); +} + +function fallbackItem(value: ProtocolFallback): ConversationItem { + return { + kind: "fallback", + reason: value.code, + detail: value.detail, + ...(value.envelope ? { id: value.envelope.id, envelope: value.envelope } : {}), + }; +} + +/** + * Converts an untrusted transport payload into a trusted renderer model. + * Plain legacy text remains a Markdown item for backwards compatibility; + * malformed JSON and invalid LineUp envelopes are always safe fallbacks. + */ export function decodeConversationItem(raw: string): ConversationItem { let parsed: unknown; try { @@ -34,27 +254,52 @@ export function decodeConversationItem(raw: string): ConversationItem { } catch { return { kind: "markdown", markdown: raw }; } - const envelope = object(parsed) as Envelope | null; - if (!envelope || envelope.v !== LINEUP_PROTOCOL_VERSION || !envelope.type?.startsWith("lineup.v1.")) { - return { kind: "fallback", reason: "invalid_envelope" }; + + const parsedEnvelope = parseEnvelope(parsed); + if (!parsedEnvelope.ok) return fallbackItem(parsedEnvelope.fallback); + const envelope = parsedEnvelope.envelope; + const payload = envelope.payload; + const base = { id: envelope.id, envelope }; + + if (!SUPPORTED_TYPES.has(envelope.type)) { + return fallbackItem({ code: "unsupported_type", detail: `Unsupported LineUp message type: ${envelope.type}`, envelope }); } - const payload = object(envelope.payload) ?? {}; + switch (envelope.type) { - case "lineup.v1.text": - return { kind: "markdown", markdown: text(payload.markdown) || text(payload.text), envelope }; - case "lineup.v1.agent.status": - return { kind: "agent-status", status: text(payload.status), detail: text(payload.detail), envelope }; - case "lineup.v1.agent.progress": - return { kind: "progress", title: text(payload.title), percent: Number(payload.percent) || 0, status: text(payload.status), envelope }; - case "lineup.v1.error": - return { kind: "error", message: text(payload.message) || "Agent 执行失败", envelope }; + case "lineup.v1.text": { + const markdown = text(payload.markdown) || text(payload.text); + return markdown ? { kind: "markdown", markdown, ...base } : fallbackItem({ code: "invalid_payload", detail: "Text payload requires text or markdown.", envelope }); + } + case "lineup.v1.agent.status": { + const status = text(payload.status); + return status + ? { kind: "agent-status", status, detail: text(payload.detail), ...base } + : fallbackItem({ code: "invalid_payload", detail: "Agent status payload requires status.", envelope }); + } + case "lineup.v1.agent.progress": { + const percent = payload.percent; + if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100) { + return fallbackItem({ code: "invalid_payload", detail: "Agent progress payload requires percent between 0 and 100.", envelope }); + } + return { kind: "progress", title: text(payload.title), percent, status: text(payload.status), ...base }; + } + case "lineup.v1.error": { + const message = text(payload.message); + return message + ? { kind: "error", message, ...(text(payload.code) ? { code: text(payload.code) } : {}), ...base } + : fallbackItem({ code: "invalid_payload", detail: "Error payload requires message.", envelope }); + } case "lineup.v1.ui.open": case "lineup.v1.ui.patch": case "lineup.v1.ui.close": - return { kind: "surface", envelope }; + return validSurfacePayload(envelope.type, payload) + ? { kind: "surface", ...base } + : fallbackItem({ code: "invalid_payload", detail: "Surface payload does not match its lifecycle contract.", envelope }); case "lineup.v1.app.call": - return { kind: "app-call", envelope }; + return validAppCallPayload(payload) + ? { kind: "app-call", ...base } + : fallbackItem({ code: "invalid_payload", detail: "App call payload requires call_id, capability, and arguments.", envelope }); default: - return { kind: "fallback", reason: "unsupported_type", envelope }; + return fallbackItem({ code: "unsupported_type", detail: `Unsupported LineUp message type: ${envelope.type}`, envelope }); } }