TypeBox

TypeBox 是一个用 TypeScript 语言写规则的工具。我们用它来制定一个叫 Gateway 的 WebSocket 聊天的规则。这些规则就像游戏说明书，告诉电脑们怎么握手、怎么提问、怎么回答、服务器怎么主动发消息。有了这些规则，电脑就能自动检查消息对不对，还能生成给其他程序（比如苹果电脑上的 App）用的代码。所有东西都从这一份规则里来，这叫做“单一事实来源”。

聊天的三种小纸条 每次通过 Gateway WebSocket 聊天，发送的都是一张小纸条，它只能是三种样子中的一种：

1. 提问纸条 (Request)：就像你问“你好吗？”，上面有 type: "req"，一个编号 id，问题名字 method，和具体内容 params。
2. 回答纸条 (Response)：就像回答“我很好！”，上面有 type: "res"，对应提问的编号 id，回答成功 ok: true 或失败 ok: false，以及回答内容 payload 或错误信息 error。
3. 事件纸条 (Event)：就像服务器主动说“开饭啦！”，上面有 type: "event"，事件名字 event，事件内容 payload，有时还有序号 seq 和状态版本 stateVersion。

怎么开始聊天？ 聊天必须从一张特殊的“提问纸条”开始，它的 method 必须是 connect（连接）。这就像见面要先说“你好”。之后，你的程序（客户端）才能问其他问题，比如 health（检查健康），或者订阅服务器主动发来的消息，比如 tick（滴答声，表示服务器还活着）。

规则文件在哪里？ 所有规则都写在 src/gateway/protocol/schema.ts 这个文件里。其他重要的文件还有：

• 检查规则的“小警察”（AJV验证器）：src/gateway/protocol/index.ts
• 处理聊天的“服务器大脑”：src/gateway/server.ts
• 苹果电脑 App 用的自动生成代码：apps/macos/Sources/OpenClawProtocol/GatewayModels.swift

怎么让规则生效？ 如果你想更新规则并生成新的说明书和代码，需要在电脑的命令行里运行这些命令：

1. pnpm protocol:gen：这个命令会根据规则，生成一份 JSON 格式的详细说明书，放在 dist/protocol.schema.json。
2. pnpm protocol:gen:swift：这个命令会根据规则，生成苹果电脑 App 需要用的代码。
3. pnpm protocol:check：这个命令会同时做上面两件事，并且检查生成的文件是不是都已经保存好了。记住哦，改完规则后，一定要运行这个命令检查一下！

规则怎么被使用？

• 在服务器那边：每张收到的小纸条，都会用“小警察”（AJV）根据规则检查一遍。特别是第一张握手纸条，必须是一张 connect 提问，而且它的内容 params 必须符合 ConnectParams 这条规则。
• 在你的程序那边：程序在用小纸条里的内容前，也会先检查事件纸条和回答纸条对不对。
• 打招呼时告诉你能聊什么：服务器在第一次回答 hello-ok 时，会告诉你的程序它支持哪些 methods（可以问的问题）和 events（会主动说的事情）。

如果你想增加一个新问题（比如 system.echo） 假设你想增加一个叫 system.echo 的新问题，它能让服务器把你发的话原样说回来。你需要按顺序做这几步：

1. 写新规则：在 src/gateway/protocol/schema.ts 文件里，增加两条新规则，一条规定提问时要带什么（比如 text 文字），一条规定回答时有什么（比如 ok: true 和同样的 text）。还要把它们加到总规则列表 ProtocolSchemas 里。
2. 增加“小警察”：在 src/gateway/protocol/index.ts 文件里，告诉“小警察”（AJV）怎么检查这个新问题的提问内容。
3. 教服务器怎么回答：在 src/gateway/server-methods/system.ts 文件里，写一小段代码，告诉服务器收到 system.echo 问题时，应该怎么处理并回答。然后，别忘了在 src/gateway/server.ts 文件的 METHODS 列表里加上 "system.echo" 这个名字。
4. 重新生成：运行 pnpm protocol:check 命令，让新的规则生效，生成新的说明书和代码。
5. 写测试和说明：给这个新功能加上测试，并在文档里记下来。

一些重要的提醒

• 版本要匹配：你的程序和服务器聊天时，会告诉对方自己支持哪个版本的规则（minProtocol 和 maxProtocol）。如果版本对不上，服务器会拒绝聊天。
• 有些问题需要“防重复钥匙”：像 send（发送）、chat.send（聊天发送）这种会改变东西的操作，提问时通常需要一个 idempotencyKey（你可以把它想成“防重复钥匙”），防止同一件事不小心做了两遍。
• 改完规则要保存：每次改完 schema.ts 里的规则，一定要记得运行 pnpm protocol:check，并且把生成的新文件（比如 dist/protocol.schema.json 和 Swift 代码）也一起保存到仓库里。