@fantaibao/ws-protocol

万流引力 桌面端（gravio-app） ↔ Web 控制台（wlyl_web） 之间的 WebSocket 协议契约。

• Zod schema：运行时校验，desktop 服务端用
• TS 类型：通过 z.infer 派生，两端都可以 import type
• WsCodec：消息编解码（JSON.parse + schema 校验 + 错误处理）

使用

pnpm add @fantaibao/ws-protocol

desktop（带运行时校验）

import { WsCodec, WsEnvelopeSchema, type WsEnvelope } from '@fantaibao/ws-protocol'

const envelope = WsCodec.decode(rawString)  // 自动校验

web（仅类型，零运行时开销）

import type { WsEnvelope, WsAccountInfo, TaskKind } from '@fantaibao/ws-protocol'

const env: WsEnvelope = JSON.parse(rawString)  // 不带 zod,自己 trust 服务端

import type 在 TS 编译时被擦除，zod 不会进 web bundle。

改契约的工作流

# 1. 改 src/index.ts
vim src/index.ts

# 2. 自测 + 构建
pnpm typecheck && pnpm build

# 3. 升版本号 + 打 tag
pnpm version patch  # 或 minor / major
git push --follow-tags

# 4. 登录 npm 并发布
npm login
npm publish --access public

# 5. desktop 端升级
cd ~/dev/gravio-app
pnpm up @fantaibao/[email protected]

# 6. web 端同样动作
cd ~/dev/wlyl_web
pnpm up @fantaibao/[email protected]

任何一端不升版本号就锁在旧版本上，不会被偷偷漂移。

版本规范

按 Semantic Versioning：

• major：删消息类型、改字段含义、改 PROTOCOL_VERSION
• minor：新增消息类型、新增可选字段
• patch：注释/JSDoc 改动、不影响行为的内部重构