@fantaibao/ws-protocol 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gravio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @fantaibao/ws-protocol
+
+万流引力 桌面端（gravio-app） ↔ Web 控制台（wlyl_web） 之间的 WebSocket 协议契约。
+
+- **Zod schema**：运行时校验，desktop 服务端用
+- **TS 类型**：通过 `z.infer` 派生，两端都可以 `import type`
+- **WsCodec**：消息编解码（JSON.parse + schema 校验 + 错误处理）
+
+## 使用
+
+```bash
+pnpm add @fantaibao/ws-protocol
+```
+
+### desktop（带运行时校验）
+
+```ts
+import { WsCodec, WsEnvelopeSchema, type WsEnvelope } from '@fantaibao/ws-protocol'
+
+const envelope = WsCodec.decode(rawString)  // 自动校验
+```
+
+### web（仅类型，零运行时开销）
+
+```ts
+import type { WsEnvelope, WsAccountInfo, TaskKind } from '@fantaibao/ws-protocol'
+
+const env: WsEnvelope = JSON.parse(rawString)  // 不带 zod,自己 trust 服务端
+```
+
+`import type` 在 TS 编译时被擦除，zod 不会进 web bundle。
+
+## 改契约的工作流
+
+```bash
+# 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/ws-protocol@1.1.0
+
+# 6. web 端同样动作
+cd ~/dev/wlyl_web
+pnpm up @fantaibao/ws-protocol@1.1.0
+```
+
+任何一端不升版本号就锁在旧版本上，**不会被偷偷漂移**。
+
+## 版本规范
+
+按 [Semantic Versioning](https://semver.org/lang/zh-CN/)：
+
+- **major**：删消息类型、改字段含义、改 PROTOCOL_VERSION
+- **minor**：新增消息类型、新增可选字段
+- **patch**：注释/JSDoc 改动、不影响行为的内部重构