grok-bot-sdk 0.0.0-stage → 0.75.8

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.75.8
+
+Protocol surface matched to the Grok Bot 0.75.8 desktop client. The package stays ESM, with no runtime dependencies.
+
+- Default `x-cursor-client-version` is `0.75.8`.
+- Login polling stops on HTTP 403 `{ "error": "sign_in_policy_violation" }` and throws `SIGN_IN_POLICY_VIOLATION`.
+- Roster reads optional `role` and `addedTeamAgentsOnly`, and returns Slack and Teams connection records plus the additional `GrokBotAgent` scalars present in 0.75.8.
+- `sendMessage` accepts `replyToId`, `replyQuote`, `taskId`, `language`, `richText`, and `machineId`. Delivery `4` (`REFUSED`) throws `SEND_REFUSED`.
+- New read methods: `listSessions`, `listTranscript`, `listAgentStatuses`, `getSendStatus`, `listAgentTasks`, `listTasks`, `listSubagents`, `listAgentTodos`, `listAgentSkills`, `listDeletedAgentIds`, `getRuntimeCapabilities`, `getSandBoxRunState`.
+- Watch events add `agent.state`, `computer.actions`, `box.state`, and `page.title.changed`. `bot.state.changed` includes `changedAtMs`.
+- CLI read-only subcommands: `bots`, `sessions`, `transcript`, `tasks`, `capabilities`, `box`.
+- Avatar derivation is unchanged (`grok-bot-0.70.2`). `pumpkin` is accepted as an explicit shape.
+
+The checksum, ghost-mode default, and desktop chat enums `source=1`, `initiator=1`, `sendSource=1` are the same values the 0.75.8 client still sends for desktop chat.
+
+## 0.1.0
+
+First release, matched to the Grok Bot 0.70.2 desktop client. From 0.75.8 on, the package version follows the Grok Bot version it targets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RongleCat
+
+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

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/avatars-row-dark.png" />
+    <img src="assets/avatars-row.png" alt="Five Grok Bot avatars. The default black circle is in the middle, with an orange cloud and a violet teardrop on the left, and a green hexagon and a blue squircle on the right." width="680" height="128" />
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">grok-bot-sdk</h1>
+
+<p align="center"><strong>Unofficial Node.js SDK for the Grok Bot desktop client protocol</strong></p>
+<p align="center"><em>Browser login · Account and bot roster · Sessions, transcript, and tasks · Normalized avatars · Send · Connect replies forwarded as SSE</em></p>
+<p align="center"><a href="https://ronglecat.github.io/grok-bot-sdk/">https://ronglecat.github.io/grok-bot-sdk/</a></p>
+
+<p align="center">
+  <a href="./README.md">English</a> ·
+  <a href="./README_ZH.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="https://ronglecat.github.io/grok-bot-sdk/"><img src="https://img.shields.io/badge/docs-API%20reference-0ea5e9" alt="API docs" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://github.com/RongleCat/grok-bot-sdk/stargazers"><img src="https://img.shields.io/github/stars/RongleCat/grok-bot-sdk?style=social" alt="GitHub stars" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22.13-339933?logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/client-Grok%20Bot%200.75.8-lightgrey" alt="Grok Bot 0.75.8" />
+  <img src="https://img.shields.io/badge/note-unofficial-yellow" alt="Unofficial" />
+</p>
+
+<p align="center">
+  <a href="https://x.com/cgnot996"><img src="https://img.shields.io/badge/X-铁柱AGI%20%40cgnot996-black?logo=x&logoColor=white" alt="X 铁柱AGI" /></a>
+  <img src="https://img.shields.io/badge/WeChat-铁柱AGI-07C160?logo=wechat&logoColor=white" alt="WeChat 铁柱AGI" />
+  <a href="https://bot.tiezhu.si/"><img src="https://img.shields.io/badge/learn-bot.tiezhu.si-111111" alt="Grok Bot learning site" /></a>
+</p>
+
+<p align="center">
+  <img src="assets/wechat/mp-search-scan.png" alt="WeChat Search 铁柱AGI — scan to follow the official account" width="420" />
+  &nbsp;&nbsp;
+  <img src="assets/wechat/community-group-qr.png" alt="Author WeChat QR — add to join the paid community" width="200" />
+</p>
+
+<p align="center"><sub>Left: WeChat official account <strong>铁柱AGI</strong>. Right: the author's personal WeChat. The paid community is invite-only — add this WeChat and ask to join.</sub></p>
+
+---
+
+> [!NOTE]
+> **About this SDK.** grok-bot-sdk reproduces the browser login and the read, send, and reply-stream calls used by the Grok Bot **0.75.8** desktop client. It is an independent open-source library by [铁柱AGI](https://x.com/cgnot996). It is **not an xAI product, not a Cursor product, and not the official Grok Bot SDK**.
+>
+> The same author also builds [Grok App](https://github.com/RongleCat/grok-app), a desktop workbench for the local Grok Build CLI. Grok App and this SDK are different programs.
+
+---
+
+## Contents
+
+- [Install](#install)
+- [Authorize](#authorize)
+- [Call](#call)
+- [What this release includes](#what-this-release-includes)
+- [Notes you should read](#notes-you-should-read)
+- [Docs](#docs)
+- [Related projects](#related-projects)
+- [Author and community](#author-and-community)
+
+## Install
+
+Node.js **22.13 or newer**. ESM only. The runtime has zero npm dependencies.
+
+The package is published from this GitHub repository. It is not on the npm registry.
+
+```sh
+npm install github:RongleCat/grok-bot-sdk
+```
+
+```js
+import { GrokBotClient, createLogin, pollLogin } from 'grok-bot-sdk';
+```
+
+## Authorize
+
+The normal path is a fresh browser login. It creates a session for this SDK and leaves the official client's saved login alone.
+
+```sh
+npx grok-bot-sdk login --out ./credentials.json
+```
+
+On macOS the command opens the system browser. Elsewhere, or with `--no-open`, it prints a `loginUrl`. Finish the login in that page. The command then writes `accessToken`, `refreshToken`, and `selectedTeamId` when the server returns one. The file mode is `0600`. The terminal output says the token is present. It does not print the token.
+
+```js
+import { readFile } from 'node:fs/promises';
+import { GrokBotClient } from 'grok-bot-sdk';
+
+const saved = JSON.parse(await readFile('./credentials.json', 'utf8'));
+const client = new GrokBotClient({
+  accessToken: saved.accessToken,
+  teamId: saved.selectedTeamId,
+});
+```
+
+You can also pass `GROK_BOT_ACCESS_TOKEN` in the environment. Keep that value out of shell history and logs.
+
+A second, optional path reads the Grok Bot session already stored on this Mac:
+
+```js
+import { desktopCredentials } from 'grok-bot-sdk/desktop';
+import { GrokBotClient } from 'grok-bot-sdk';
+
+const client = new GrokBotClient(await desktopCredentials());
+```
+
+macOS shows the normal Keychain prompt for `Grok Bot Safe Storage`. Approve it yourself. If that stored token is no longer accepted, stop and use `login`.
+
+Check the session without printing the account:
+
+```sh
+npx grok-bot-sdk whoami --token-file ./credentials.json
+```
+
+The full sequence, poll responses, headers, and the Mac path are in the [authorization guide](https://ronglecat.github.io/grok-bot-sdk/guide/auth).
+
+## Call
+
+```js
+const me = await client.getMe();
+const { bots, truncated } = await client.listBots();
+const bot = bots[0];
+
+const sent = await client.sendMessage({
+  botId: bot.id,
+  sessionId: bot.sessionId,
+  text: 'Summarize the notes I just sent.',
+});
+
+for await (const event of client.watchBot({
+  botId: bot.id,
+  sessionId: bot.sessionId,
+})) {
+  if (event.type === 'message') {
+    // Replace the bubble for event.data.entryId with event.data.text.
+  }
+}
+```
+
+A backend that already authenticates its own user can return the SDK response directly:
+
+```js
+return client.botEventsSSE({
+  botId: authorizedBot.id,
+  sessionId: authorizedBot.sessionId,
+  resumeFrom: request.headers.get('last-event-id') || undefined,
+  signal: request.signal,
+});
+```
+
+`Bot.id` is the agent UUID. Every bot includes `avatarShape`, `avatarColor`, and a normalized `avatar` object. When the roster omits a valid shape or color, the SDK derives that field from the agent UUID. The shape and the color are decided separately.
+
+`examples/list-bots.mjs` prints the roster summary from a saved credentials file.
+
+## What this release includes
+
+Verified against Grok Bot 0.75.8:
+
+- One browser login continued into account read and the cloud bot roster.
+- The same read path works with the Mac client's existing session.
+- Roster records come back with one avatar shape, whether the server sent the fields or the SDK derived them. The avatar hash is still `grok-bot-0.70.2`. `pumpkin` is explicit only.
+- `WatchGrokBotTranscripts` connects with Connect JSON, and an existing reply was forwarded through `botEventsSSE`.
+- Read calls: `listSessions`, `listTranscript`, `listAgentStatuses`, `getSendStatus`, `listAgentTasks`, `listTasks`, `listSubagents`, `listAgentTodos`, `listAgentSkills`, `listDeletedAgentIds`, `getRuntimeCapabilities`, and `getSandBoxRunState`.
+- Watch events also include `agent.state`, `computer.actions`, `box.state`, and `page.title.changed`.
+- Offline tests cover login URL shape, avatar vectors, frame parsing, cursors, cancellation, SSE framing, send results, and the new read records.
+
+The default client version string is `0.75.8`. Pass `version` when you know the client you are matching. The CLI also has read-only subcommands: `bots`, `sessions`, `transcript`, `tasks`, `capabilities`, and `box`.
+
+## Notes you should read
+
+These limits are part of the contract. The [notes page](https://ronglecat.github.io/grok-bot-sdk/guide/notes) lists each one with the behavior to expect.
+
+- The access token is an account credential. Store it like a password. The SDK does not refresh it, does not log it out, and does not revoke it when the process exits.
+- `truncated: true` means the roster is incomplete. `includeTeamAgents` can include team records.
+- `sendMessage` returning `accepted-box`, `accepted-temporal`, or `duplicate` means the server accepted delivery. It does not mean the bot has read or answered. `SEND_UNCONFIRMED` means you must not automatically send again.
+- `attachmentPaths` are server references from an upload that already finished. This package does not upload local files and does not wake a cloud computer.
+- Reply events carry the current full text of one transcript entry. Per-token streaming was not verified. The shape is not an OpenAI Chat Completions stream.
+- The SDK does not reconnect, does not fill in omitted entry bodies, and does not render avatar animation.
+- Put the account token on your server. The browser `EventSource` should call your backend.
+
+## Docs
+
+The API site is VitePress, deployed with GitHub Pages: [ronglecat.github.io/grok-bot-sdk](https://ronglecat.github.io/grok-bot-sdk/).
+
+English and Chinese are both in the site. The reference covers `GrokBotClient`, event types, SSE frames, avatar derivation, error codes, and the HTTP endpoints this SDK calls.
+
+```sh
+npm install
+npm test
+npm run docs:dev
+```
+
+## Related projects
+
+| Project | What it is |
+|---|---|
+| [Grok App](https://github.com/RongleCat/grok-app) | Open-source desktop workbench for the local Grok Build CLI. [grok-app.com](https://grok-app.com) |
+| [awesome-grok-bot](https://github.com/RongleCat/awesome-grok-bot) | Grok Bot community index |
+| [Grok Bot learning site](https://bot.tiezhu.si/) | From zero to a bot team: install, routines, cases, usage |
+
+## Author and community
+
+| Channel | Where |
+|---|---|
+| X | [@cgnot996 (铁柱AGI)](https://x.com/cgnot996) |
+| WeChat official account | Search **铁柱AGI**, or scan the left code above |
+| Paid community | Add the author's WeChat with the right code, then ask to join |
+| Learning site | [bot.tiezhu.si](https://bot.tiezhu.si/) |
+
+The avatars at the top are the Grok Bot shapes and colors, with the default black circle in the middle. They are not an xAI logo.
+
+MIT License. Copyright 2026 RongleCat.

package/README_ZH.md

@@ -0,0 +1,213 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/avatars-row-dark.png" />
+    <img src="assets/avatars-row.png" alt="一排五个 Grok Bot 头像。中间是默认的黑色圆形，左边是橙色云朵和紫色水滴，右边是绿色六边形和蓝色圆角方块。" width="680" height="128" />
+  </picture>
+</p>
+
+<h1 align="center">grok-bot-sdk</h1>
+
+<p align="center"><strong>Grok Bot 桌面客户端协议的非官方 Node.js SDK</strong></p>
+<p align="center"><em>浏览器登录 · 账号与 Bot 名单 · 会话、转录与任务 · 统一头像 · 发送 · Connect 回复转发为 SSE</em></p>
+<p align="center"><a href="https://ronglecat.github.io/grok-bot-sdk/zh/">https://ronglecat.github.io/grok-bot-sdk/zh/</a></p>
+
+<p align="center">
+  <a href="./README.md">English</a> ·
+  <a href="./README_ZH.md">中文</a>
+</p>
+
+<p align="center">
+  <a href="https://ronglecat.github.io/grok-bot-sdk/zh/"><img src="https://img.shields.io/badge/docs-接口文档-0ea5e9" alt="接口文档" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://github.com/RongleCat/grok-bot-sdk/stargazers"><img src="https://img.shields.io/github/stars/RongleCat/grok-bot-sdk?style=social" alt="GitHub stars" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D22.13-339933?logo=node.js&logoColor=white" alt="Node.js" />
+  <img src="https://img.shields.io/badge/client-Grok%20Bot%200.75.8-lightgrey" alt="Grok Bot 0.75.8" />
+  <img src="https://img.shields.io/badge/note-unofficial-yellow" alt="非官方" />
+</p>
+
+<p align="center">
+  <a href="https://x.com/cgnot996"><img src="https://img.shields.io/badge/X-铁柱AGI%20%40cgnot996-black?logo=x&logoColor=white" alt="X 铁柱AGI" /></a>
+  <img src="https://img.shields.io/badge/微信公众号-铁柱AGI-07C160?logo=wechat&logoColor=white" alt="微信公众号 铁柱AGI" />
+  <a href="https://bot.tiezhu.si/"><img src="https://img.shields.io/badge/学习站-bot.tiezhu.si-111111" alt="Grok Bot 学习站" /></a>
+</p>
+
+<p align="center">
+  <img src="assets/wechat/mp-search-scan.png" alt="微信搜一搜 铁柱AGI，扫码关注公众号" width="420" />
+  &nbsp;&nbsp;
+  <img src="assets/wechat/community-group-qr.png" alt="作者个人微信二维码，添加后可申请加入付费交流群" width="200" />
+</p>
+
+<p align="center"><sub>左：微信公众号「铁柱AGI」。右：作者个人微信。付费交流群由作者邀请进入，扫码添加微信后说明来意。</sub></p>
+
+---
+
+> [!NOTE]
+> **关于这个 SDK。** grok-bot-sdk 复现 Grok Bot **0.75.8** 桌面客户端使用的浏览器登录，以及读取账号、读取名单、发送消息和订阅回复。作者是 [铁柱AGI](https://x.com/cgnot996)。它**不是 xAI 官方产品，不是 Cursor 官方产品，也不是 Grok Bot 官方 SDK**。
+>
+> 同一作者的 [Grok App](https://github.com/RongleCat/grok-app) 是本机 Grok Build CLI 的桌面工作台。Grok App 和这个 SDK 是两个程序。
+
+---
+
+## 目录
+
+- [安装](#安装)
+- [授权](#授权)
+- [调用](#调用)
+- [这一版包含什么](#这一版包含什么)
+- [使用前要知道的事](#使用前要知道的事)
+- [接口文档](#接口文档)
+- [相关项目](#相关项目)
+- [作者与社区](#作者与社区)
+
+## 安装
+
+需要 Node.js **22.13 或更高版本**。只提供 ESM。运行时没有 npm 依赖。
+
+包从本 GitHub 仓库安装，尚未发布到 npm registry。
+
+```sh
+npm install github:RongleCat/grok-bot-sdk
+```
+
+```js
+import { GrokBotClient, createLogin, pollLogin } from 'grok-bot-sdk';
+```
+
+## 授权
+
+常规路径是一次新的浏览器登录。它为这个 SDK 建立独立会话，不改写官方客户端已经保存的登录。
+
+```sh
+npx grok-bot-sdk login --out ./credentials.json
+```
+
+在 macOS 上，命令会打开系统浏览器。其他系统，或者加上 `--no-open` 时，终端只打印 `loginUrl`。在页面里完成登录后，命令把 `accessToken`、`refreshToken`，以及服务端返回时的 `selectedTeamId`，写入指定文件。文件权限是 `0600`。终端只说明令牌已经写入，不打印令牌本身。
+
+```js
+import { readFile } from 'node:fs/promises';
+import { GrokBotClient } from 'grok-bot-sdk';
+
+const saved = JSON.parse(await readFile('./credentials.json', 'utf8'));
+const client = new GrokBotClient({
+  accessToken: saved.accessToken,
+  teamId: saved.selectedTeamId,
+});
+```
+
+也可以把访问令牌放在环境变量 `GROK_BOT_ACCESS_TOKEN` 里。不要把它留在 shell 历史或日志里。
+
+另一条可选路径读取这台 Mac 上 Grok Bot 已经保存的会话：
+
+```js
+import { desktopCredentials } from 'grok-bot-sdk/desktop';
+import { GrokBotClient } from 'grok-bot-sdk';
+
+const client = new GrokBotClient(await desktopCredentials());
+```
+
+macOS 会为钥匙串项目 `Grok Bot Safe Storage` 弹出系统授权。由你自己点允许。若这份旧令牌已经被拒绝，停下来，改用 `login`。
+
+检查会话时不打印账号内容：
+
+```sh
+npx grok-bot-sdk whoami --token-file ./credentials.json
+```
+
+完整顺序、轮询响应、请求头和 Mac 路径见[授权说明](https://ronglecat.github.io/grok-bot-sdk/zh/guide/auth)。
+
+## 调用
+
+```js
+const me = await client.getMe();
+const { bots, truncated } = await client.listBots();
+const bot = bots[0];
+
+const sent = await client.sendMessage({
+  botId: bot.id,
+  sessionId: bot.sessionId,
+  text: '总结我刚发过去的笔记。',
+});
+
+for await (const event of client.watchBot({
+  botId: bot.id,
+  sessionId: bot.sessionId,
+})) {
+  if (event.type === 'message') {
+    // 用 event.data.text 替换 event.data.entryId 对应的那条消息。
+  }
+}
+```
+
+已经认证过自己用户的后端，可以直接返回 SDK 的响应：
+
+```js
+return client.botEventsSSE({
+  botId: authorizedBot.id,
+  sessionId: authorizedBot.sessionId,
+  resumeFrom: request.headers.get('last-event-id') || undefined,
+  signal: request.signal,
+});
+```
+
+`Bot.id` 是 Bot 的 UUID。每条记录都有 `avatarShape`、`avatarColor` 和统一的 `avatar` 对象。名单缺少有效形状或颜色时，SDK 用 agent UUID 补上该字段。形状和颜色分开决定。
+
+`examples/list-bots.mjs` 用保存的凭据文件打印名单摘要。
+
+## 这一版包含什么
+
+对照 Grok Bot 0.75.8 核对过：
+
+- 一次浏览器登录可以接着读账号和云端 Bot 名单。
+- 用 Mac 客户端里已有的会话，可以走同一条读取路径。
+- 名单里的每条记录都带回同一种头像结构。服务端带了字段就用字段，缺了就按 UUID 推算。头像哈希仍是 `grok-bot-0.70.2`。`pumpkin` 只在显式指定时出现。
+- `WatchGrokBotTranscripts` 以 Connect JSON 接通，既有回复可以经 `botEventsSSE` 转发。
+- 只读调用：`listSessions`、`listTranscript`、`listAgentStatuses`、`getSendStatus`、`listAgentTasks`、`listTasks`、`listSubagents`、`listAgentTodos`、`listAgentSkills`、`listDeletedAgentIds`、`getRuntimeCapabilities`、`getSandBoxRunState`。
+- 订阅事件还包含 `agent.state`、`computer.actions`、`box.state` 和 `page.title.changed`。
+- 离线测试覆盖登录 URL、头像向量、帧解析、游标、取消、SSE 帧、发送结果，以及新增的只读记录。
+
+默认客户端版本字符串是 `0.75.8`。你知道自己要匹配的客户端版本时，传入 `version`。CLI 还有只读子命令：`bots`、`sessions`、`transcript`、`tasks`、`capabilities`、`box`。
+
+## 使用前要知道的事
+
+这些边界就是这份 SDK 的约定。[注意事项](https://ronglecat.github.io/grok-bot-sdk/zh/guide/notes)逐条写了会看到的行为。
+
+- 访问令牌是账号凭据，按密码保管。SDK 不刷新它，不替你登出，进程退出也不等于服务端撤销。
+- `truncated: true` 表示名单不完整。`includeTeamAgents` 可能带上团队记录。
+- `sendMessage` 返回 `accepted-box`、`accepted-temporal` 或 `duplicate`，只表示服务端接受了投递，不表示 Bot 已经阅读或回复。遇到 `SEND_UNCONFIRMED` 时，不要自动再发一次。
+- `attachmentPaths` 是已经上传完成的服务端引用。这个包不上传本地文件，也不唤醒云电脑。
+- 回复事件给出的是某一条记录当前的完整文本。逐 token 输出尚未验证。它也不是 OpenAI Chat Completions 的流格式。
+- SDK 不自动重连，不补齐被省略的正文，也不渲染头像动画。
+- 账号令牌放在你自己的服务端。浏览器里的 `EventSource` 只访问你的后端。
+
+## 接口文档
+
+文档站使用 VitePress，由 GitHub Pages 发布：[ronglecat.github.io/grok-bot-sdk/zh/](https://ronglecat.github.io/grok-bot-sdk/zh/)。
+
+站点包含中文和英文。参考页写明 `GrokBotClient`、事件类型、SSE 帧、头像推算、错误码，以及这个 SDK 实际调用的 HTTP 接口。
+
+```sh
+npm install
+npm test
+npm run docs:dev
+```
+
+## 相关项目
+
+| 项目 | 是什么 |
+|---|---|
+| [Grok App](https://github.com/RongleCat/grok-app) | 本机 Grok Build CLI 的开源桌面工作台。[grok-app.com](https://grok-app.com) |
+| [awesome-grok-bot](https://github.com/RongleCat/awesome-grok-bot) | Grok Bot 社区索引 |
+| [Grok Bot 学习站](https://bot.tiezhu.si/) | 从装好客户端到带一支 Bot 团队：安装、例程、案例、额度 |
+
+## 作者与社区
+
+| 渠道 | 入口 |
+|---|---|
+| X | [@cgnot996（铁柱AGI）](https://x.com/cgnot996) |
+| 微信公众号 | 搜索 **铁柱AGI**，或扫描上方左侧二维码 |
+| 付费交流群 | 扫描上方右侧二维码添加作者微信，再说明要入群 |
+| 学习站 | [bot.tiezhu.si](https://bot.tiezhu.si/) |
+
+页顶是一排 Grok Bot 头像，中间是默认的黑色圆形，左右是另外四种形状和颜色。这不是 xAI 的标志。
+
+MIT License。Copyright 2026 RongleCat。

package/avatar.d.mts

@@ -0,0 +1,37 @@
+export type AvatarSource = 'explicit' | 'id-default';
+export interface CharacterAvatar {
+  shape: string;
+  color: string;
+  baseHex: string;
+  lightHex: string;
+  darkHex: string;
+}
+export interface ResolvedAvatar {
+  algorithmVersion: string;
+  kind: 'character' | 'picture';
+  character: CharacterAvatar;
+  sources: { shape: AvatarSource; color: AvatarSource };
+  picture: { url: string | null; version: string | null } | null;
+}
+export interface CloudAvatarRecord {
+  agentId: string;
+  avatarShape?: string | null;
+  avatarColor?: string | null;
+  avatarUrl?: string | null;
+  avatarDataUrl?: string | null;
+  avatarVersion?: string | null;
+  [key: string]: unknown;
+}
+export const AVATAR_ALGORITHM_VERSION: string;
+export const DEFAULT_SHAPES: readonly string[];
+export const VALID_SHAPES: readonly string[];
+export const DEFAULT_COLORS: readonly string[];
+export function hashBotId(key: string): number;
+export function deriveDefaultAvatar(key: string): CharacterAvatar & {
+  algorithmVersion: string;
+  hash: number;
+  shapeHash: number;
+  shapeIndex: number;
+  colorIndex: number;
+};
+export function resolveAgentAvatar(agent: CloudAvatarRecord): ResolvedAvatar;

package/avatar.mjs

@@ -0,0 +1,69 @@
+// Parameter derivation verified against Grok Bot 0.70.2 and again against 0.75.8.
+// 0.75.8 keeps the same hash, salts, default shapes, and palette. It adds one
+// explicit shape, pumpkin, behind the sand_pumpkin_2026 picker gate. Pumpkin is
+// not part of the default hash set. This module does not load or execute the
+// official renderer or its assets.
+export const AVATAR_ALGORITHM_VERSION='grok-bot-0.70.2';
+export const DEFAULT_SHAPES=Object.freeze(['blob','pebble','squircle','tablet','wedge','hex','cloud','teardrop']);
+export const VALID_SHAPES=Object.freeze(['blob','pebble','bean','egg','squircle','tablet','capsule','cylinder','hex','gem','crystal','wedge','shield','dome','arch','cloud','teardrop','leaf','square','sparkle','clover','flower','heart','house','star','pumpkin']);
+export const DEFAULT_COLORS=Object.freeze(['brown','red','orange','yellow','green','cyan','blue','violet','magenta','gray']);
+const PALETTE=Object.freeze(Object.fromEntries([
+  ['black','#000000','#000000','#FFFFFF'],
+  ['brown','#936439','#A27952','#855C36'],
+  ['red','#FF263C','#FF3E51','#E02135'],
+  ['orange','#FF6700','#FF781C','#FF6700'],
+  ['yellow','#FF9800','#FFAF38','#FF9800'],
+  ['green','#00C972','#00C972','#009957'],
+  ['cyan','#00BCA6','#1CC3B0','#00A592'],
+  ['blue','#1084FE','#2A92FE','#0E74E0'],
+  ['violet','#9159FE','#A97EFE','#804EE0'],
+  ['magenta','#FF309B','#FF5EB1','#E02A88'],
+  ['gray','#777777','#959595','#777777'],
+].map(([color,baseHex,lightHex,darkHex])=>[color,Object.freeze({baseHex,lightHex,darkHex})])));
+
+export function hashBotId(key){
+  if(typeof key!=='string'||!key.length)throw new Error('AVATAR_KEY_REQUIRED');
+  let hash=2166136261;
+  for(let i=0;i<key.length;i++)hash=Math.imul(hash^key.charCodeAt(i),16777619);
+  return hash>>>0;
+}
+
+export function deriveDefaultAvatar(key){
+  const hash=hashBotId(key);
+  let shapeHash=hash|0;
+  shapeHash=Math.imul(shapeHash^(shapeHash>>>16),73244475);
+  shapeHash=Math.imul(shapeHash^(shapeHash>>>13),3266489909);
+  shapeHash=(shapeHash^(shapeHash>>>16))>>>0;
+  const shapeIndex=shapeHash%DEFAULT_SHAPES.length;
+  // Keep the two independent version salts even though they cancel in 0.70.2.
+  const identitySaltVersion=1,paletteSaltVersion=1;
+  const identitySeed=(hash^Math.imul(identitySaltVersion,2654435769))>>>0;
+  let seed=(identitySeed^Math.imul(paletteSaltVersion,2654435769))>>>0;
+  seed=(seed+1831565813)|0;
+  let sample=Math.imul(seed^(seed>>>15),1|seed);
+  sample=(sample+Math.imul(sample^(sample>>>7),61|sample))^sample;
+  const random=((sample^(sample>>>14))>>>0)/4294967296;
+  const colorIndex=Math.floor(random*DEFAULT_COLORS.length);
+  const shape=DEFAULT_SHAPES[shapeIndex],color=DEFAULT_COLORS[colorIndex];
+  return {algorithmVersion:AVATAR_ALGORITHM_VERSION,hash,shapeHash,shapeIndex,colorIndex,shape,color,...PALETTE[color]};
+}
+
+// Input is a raw cloud ListGrokBotAgents record: its numeric `id` is not the avatar key.
+export function resolveAgentAvatar(agent){
+  if(typeof agent?.agentId!=='string'||!agent.agentId.length)throw new Error('AVATAR_AGENT_ID_REQUIRED');
+  const derived=deriveDefaultAvatar(agent.agentId);
+  const explicitShape=VALID_SHAPES.includes(agent.avatarShape);
+  const explicitColor=typeof agent.avatarColor==='string'&&Object.hasOwn(PALETTE,agent.avatarColor);
+  const shape=explicitShape?agent.avatarShape:derived.shape;
+  const color=explicitColor?agent.avatarColor:derived.color;
+  const nonempty=value=>typeof value==='string'&&value.length>0;
+  const url=nonempty(agent.avatarUrl)?agent.avatarUrl:nonempty(agent.avatarDataUrl)?agent.avatarDataUrl:null;
+  const version=nonempty(agent.avatarVersion)?agent.avatarVersion:null;
+  return {
+    algorithmVersion:AVATAR_ALGORITHM_VERSION,
+    kind:url||version?'picture':'character',
+    character:{shape,color,...PALETTE[color]},
+    sources:{shape:explicitShape?'explicit':'id-default',color:explicitColor?'explicit':'id-default'},
+    picture:url||version?{url,version}:null,
+  };
+}