eggs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eggs

Quick Start

快速开始

When the user asks to spawn the desktop companion, including

/eggs

, run the bundled runtime from this skill directory:

bash

python3 scripts/egg_desktop.py start

When the user asks to stop it:

bash

python3 scripts/egg_desktop.py stop

For status:

bash

python3 scripts/egg_desktop.py status

For restart:

bash

python3 scripts/egg_desktop.py restart

Remote interaction is opt-in. To connect this skill to a separately deployed remote sprite server:

bash

python3 scripts/egg_desktop.py remote server http://localhost:8787
python3 scripts/egg_desktop.py remote upload dino
python3 scripts/egg_desktop.py remote
python3 scripts/egg_desktop.py remote status

remote

joins the server-side random waiting pool by default (equivalent to

remote random

). After a match is found, the server creates a temporary private room for that pair.

For invite rooms:

bash

python3 scripts/egg_desktop.py remote room ABC123

To leave:

bash

python3 scripts/egg_desktop.py remote leave

For state changes:

bash

python3 scripts/egg_desktop.py state unborn
python3 scripts/egg_desktop.py state ready
python3 scripts/egg_desktop.py state hatching
python3 scripts/egg_desktop.py state hatched
python3 scripts/egg_desktop.py state walk
python3 scripts/egg_desktop.py state sleep
python3 scripts/egg_desktop.py state eat
python3 scripts/egg_desktop.py state drink
python3 scripts/egg_desktop.py state play
python3 scripts/egg_desktop.py state roar
python3 scripts/egg_desktop.py state attack

To install a replacement spritesheet:

bash

python3 scripts/egg_desktop.py spritesheet /path/to/dino.png dino
python3 scripts/egg_desktop.py restart

当用户请求生成桌面助手（包括输入

/eggs

）时，运行本技能目录中的捆绑运行时：

bash

python3 scripts/egg_desktop.py start

当用户要求停止时：

bash

python3 scripts/egg_desktop.py stop

查看状态：

bash

python3 scripts/egg_desktop.py status

重启：

bash

python3 scripts/egg_desktop.py restart

远程交互为可选功能。如需将本技能连接到单独部署的远程精灵服务器：

bash

python3 scripts/egg_desktop.py remote server http://localhost:8787
python3 scripts/egg_desktop.py remote upload dino
python3 scripts/egg_desktop.py remote
python3 scripts/egg_desktop.py remote status

默认情况下，

remote

会加入服务器端的随机等待池（等同于

remote random

）。匹配成功后，服务器会为该配对创建临时私人房间。

邀请房间操作：

bash

python3 scripts/egg_desktop.py remote room ABC123

退出房间：

bash

python3 scripts/egg_desktop.py remote leave

状态更改：

bash

python3 scripts/egg_desktop.py state unborn
python3 scripts/egg_desktop.py state ready
python3 scripts/egg_desktop.py state hatching
python3 scripts/egg_desktop.py state hatched
python3 scripts/egg_desktop.py state walk
python3 scripts/egg_desktop.py state sleep
python3 scripts/egg_desktop.py state eat
python3 scripts/egg_desktop.py state drink
python3 scripts/egg_desktop.py state play
python3 scripts/egg_desktop.py state roar
python3 scripts/egg_desktop.py state attack

安装替换精灵图：

bash

python3 scripts/egg_desktop.py spritesheet /path/to/dino.png dino
python3 scripts/egg_desktop.py restart

Sprite Tools

精灵工具

Use the bundled Swift tools in

tools/

when asked to process, extract, validate, or merge desktop companion sprite sheets. When tools are run with

--name <sprite>

, they write

<sprite>.png

and

<sprite>.json

to the requested output directory and also install copies to

~/.codex/eggs/<sprite>.png

and

~/.codex/eggs/<sprite>.json

. If extraction is run without

--name

, use the input image stem and write

<input-name>_spritesheet.png/json

Build tools into a temporary location instead of committing platform-specific binaries:

bash

mkdir -p .swift-module-cache
CLANG_MODULE_CACHE_PATH="$PWD/.swift-module-cache" \
swiftc -module-cache-path "$PWD/.swift-module-cache" \
  eggs/tools/extract_sprite.swift \
  -o /tmp/extract_sprite

Extract a bordered grid:

bash

/tmp/extract_sprite <input.png> <output-dir> --prefix <name>

Extract a borderless regular grid:

bash

/tmp/extract_sprite <input.png> <output-dir> \
  --grid uniform \
  --columns <n> \
  --rows <n> \
  --prefix <name>

Force multiple source sheets into a common frame canvas:

bash

/tmp/extract_sprite <input.png> <output-dir> --frame-size 251 --prefix <name>

Merge extracted sheets vertically:

bash

CLANG_MODULE_CACHE_PATH="$PWD/.swift-module-cache" \
swiftc -module-cache-path "$PWD/.swift-module-cache" \
  eggs/tools/merge_spritesheets.swift \
  -o /tmp/merge_spritesheets

/tmp/merge_spritesheets <output-dir> [--name <sprite>] <sheet-a.json> <sheet-b.json>

Validation helpers:

bash

swiftc eggs/tools/check_sprite.swift -o /tmp/check_sprite
swiftc eggs/tools/bounds_sprite.swift -o /tmp/bounds_sprite

当需要处理、提取、验证或合并桌面助手精灵图时，使用

tools/

目录中的捆绑Swift工具。当工具使用

--name <sprite>

参数运行时，会将

<sprite>.png

和

<sprite>.json

写入指定的输出目录，同时将副本安装到

~/.codex/eggs/<sprite>.png

和

~/.codex/eggs/<sprite>.json

。如果提取时未使用

--name

参数，则使用输入图像的文件名前缀，生成

<input-name>_spritesheet.png/json

。

将工具编译到临时位置，而非提交特定平台的二进制文件：

bash

mkdir -p .swift-module-cache
CLANG_MODULE_CACHE_PATH="$PWD/.swift-module-cache" \
swiftc -module-cache-path "$PWD/.swift-module-cache" \
  eggs/tools/extract_sprite.swift \
  -o /tmp/extract_sprite

提取带边框的网格：

bash

/tmp/extract_sprite <input.png> <output-dir> --prefix <name>

提取无边框的规则网格：

bash

/tmp/extract_sprite <input.png> <output-dir> \
  --grid uniform \
  --columns <n> \
  --rows <n> \
  --prefix <name>

强制将多个源图合并到统一的帧画布中：

bash

/tmp/extract_sprite <input.png> <output-dir> --frame-size 251 --prefix <name>

垂直合并提取的精灵图：

bash

CLANG_MODULE_CACHE_PATH="$PWD/.swift-module-cache" \
swiftc -module-cache-path "$PWD/.swift-module-cache" \
  eggs/tools/merge_spritesheets.swift \
  -o /tmp/merge_spritesheets

/tmp/merge_spritesheets <output-dir> [--name <sprite>] <sheet-a.json> <sheet-b.json>

验证辅助工具：

bash

swiftc eggs/tools/check_sprite.swift -o /tmp/check_sprite
swiftc eggs/tools/bounds_sprite.swift -o /tmp/bounds_sprite

Runtime Behavior

运行时行为

Use only the bundled
```
scripts/egg_desktop.py
```
; it has no third-party Python dependencies.
On macOS, the manager compiles and launches the bundled native Swift/Cocoa overlay at first run. This requires
```
python3
```
and the macOS Swift compiler, but no npm, Electron, PyPI packages, or external assets.
When remote interaction is enabled, the Swift runtime remains the display runtime. A separate Python sidecar handles remote WebSocket sync and writes
```
~/.codex/eggs/remote-peers.json
```
for Swift to render remote peers.
On non-macOS, the manager falls back to its Python/Tk runtime. If Tkinter is unavailable, report that the local Python build cannot display the fallback GUI.
The script launches a detached local GUI process and stores its PID/log under
```
~/.codex/eggs/
```
.
Re-running
```
start
```
should not create duplicates; use
```
restart
```
when the user wants a fresh companion.
The runtime reads the current sprite and state from
```
~/.codex/eggs/state.json
```
.
The runtime reads optional user animation names from
```
~/.codex/eggs/config.json
```
under
```
animations.<sprite>.<name>
```
, where each animation object uses
```
row
```
and
```
loop
```
.
The runtime first looks for a user-installed sprite at
```
~/.codex/eggs/<sprite>.png
```
with optional
```
~/.codex/eggs/<sprite>.json
```
, then bundled skill assets at
```
assets/<sprite>.png
```
and
```
assets/<sprite>.json
```
, then falls back to a simple procedural placeholder drawing.
Resolve bundled assets relative to this installed skill directory; never rely on the original repo path or any
```
/Users/...
```
absolute path.
Do not hardcode the frame size. The animation runtime reads
```
frameWidth
```
and
```
frameHeight
```
from
```
<sprite>.json
```
to slice the PNG and size the desktop window. It only falls back to 251x251 if metadata is missing or invalid.
The bundled spritesheet currently has 251x251 frames in a 5x11 regular grid.
```
assets/dino.json
```
keeps
```
image
```
as
```
dino.png
```
, relative to the JSON file's own directory. Generated sprite metadata should stay portable in the same way.

Without custom config, each row is a state:

unborn

ready

hatching

hatched

walk

sleep

eat

drink

play

roar

attack

With custom config, accept animation names from

config.json

, for example

"idle": { "row": 3, "loop": true }

"attackOnce": { "row": 10, "loop": false }

, or

"roar3": { "row": 9, "loop": 3 }

Chinese state requests are supported through aliases such as
```
睡觉
```
,
```
吃鸡腿
```
,
```
喝水
```
,
```
玩耍
```
,
```
咆哮
```
, and
```
攻击
```
.
The
```
state
```
and
```
sprite
```
commands write
```
~/.codex/eggs/state.json
```
; running windows poll it and switch animation rows or sprite assets without restarting.
The desktop window can be repositioned by dragging it with the mouse.
Remote settings are stored in
```
~/.codex/eggs/remote.json
```
, anonymous device identity in
```
~/.codex/eggs/client.json
```
, and downloaded remote peer indexes in
```
~/.codex/eggs/remote/<peer_id>/
```
with shared blob files under
```
~/.codex/eggs/remote/blobs/
```
. Remote cache never overwrites local
```
<sprite>.png/json
```
.
Remote upload remembers the selected sprite name, and room/random interaction uses
```
device_id + sprite name
```
for the live WebSocket session rather than resolving peers through the public sprite detail endpoint.
The remote Go server is not part of the installed skill; it lives at the repository root under
```
server/
```
and should be deployed separately.
Sprite preparation tools are bundled under
```
tools/
```
; do not rely on old root-level compiled binaries.

仅使用捆绑的
```
scripts/egg_desktop.py
```
；它没有第三方Python依赖。
在macOS系统上，管理器会在首次运行时编译并启动捆绑的原生Swift/Cocoa覆盖层。这需要
```
python3
```
和macOS Swift编译器，但不需要npm、Electron、PyPI包或外部资源。
启用远程交互后，Swift运行时仍作为显示运行时。独立的Python辅助进程处理远程WebSocket同步，并将
```
~/.codex/eggs/remote-peers.json
```
写入供Swift渲染远程伙伴。
在非macOS系统上，管理器会回退到Python/Tk运行时。如果Tkinter不可用，则报告本地Python构建无法显示备用GUI。
该脚本会启动一个独立的本地GUI进程，并将其PID/日志存储在
```
~/.codex/eggs/
```
目录下。
重复运行
```
start
```
不应创建重复进程；当用户需要全新的助手时，请使用
```
restart
```
。
运行时从
```
~/.codex/eggs/state.json
```
读取当前精灵和状态。
运行时从
```
~/.codex/eggs/config.json
```
中的
```
animations.<sprite>.<name>
```
读取可选的用户动画名称，其中每个动画对象使用
```
row
```
和
```
loop
```
参数。
运行时首先在
```
~/.codex/eggs/<sprite>.png
```
（可选搭配
```
~/.codex/eggs/<sprite>.json
```
）中查找用户安装的精灵，然后在技能捆绑资源
```
assets/<sprite>.png
```
和
```
assets/<sprite>.json
```
中查找，最后回退到简单的程序生成占位图。
相对于已安装的技能目录解析捆绑资源；切勿依赖原始仓库路径或任何
```
/Users/...
```
绝对路径。
不要硬编码帧大小。动画运行时从
```
<sprite>.json
```
读取
```
frameWidth
```
和
```
frameHeight
```
来切割PNG并设置桌面窗口大小。只有当元数据缺失或无效时，才会回退到251x251。
当前捆绑的精灵图在5x11规则网格中包含251x251的帧。
```
assets/dino.json
```
中的
```
image
```
字段设为
```
dino.png
```
，相对于JSON文件自身的目录。生成的精灵元数据应保持同样的可移植性。
若无自定义配置，每一行对应一个状态：
```
unborn
```
（未孵化）、
```
ready
```
（就绪）、
```
hatching
```
（孵化中）、
```
hatched
```
（已孵化）、
```
walk
```
（行走）、
```
sleep
```
（睡眠）、
```
eat
```
（进食）、
```
drink
```
（饮水）、
```
play
```
（玩耍）、
```
roar
```
（咆哮）、
```
attack
```
（攻击）。

若有自定义配置，接受

config.json

中的动画名称，例如

"idle": { "row": 3, "loop": true }

、

"attackOnce": { "row": 10, "loop": false }

或

"roar3": { "row": 9, "loop": 3 }

。

支持中文状态请求，对应别名如
```
睡觉
```
、
```
吃鸡腿
```
、
```
喝水
```
、
```
玩耍
```
、
```
咆哮
```
和
```
攻击
```
。
```
state
```
和
```
sprite
```
命令会写入
```
~/.codex/eggs/state.json
```
；运行中的窗口会轮询该文件，无需重启即可切换动画行或精灵资源。
可通过鼠标拖动重新定位桌面窗口。
远程设置存储在
```
~/.codex/eggs/remote.json
```
中，匿名设备标识存储在
```
~/.codex/eggs/client.json
```
中，下载的远程伙伴索引存储在
```
~/.codex/eggs/remote/<peer_id>/
```
中，共享Blob文件存储在
```
~/.codex/eggs/remote/blobs/
```
下。远程缓存永远不会覆盖本地
```
<sprite>.png/json
```
。
远程上传会记住所选的精灵名称，房间/随机交互使用
```
device_id + sprite name
```
作为实时WebSocket会话标识，而非通过公共精灵详情端点解析伙伴。
远程Go服务器不属于已安装的技能；它位于仓库根目录的
```
server/
```
下，需单独部署。
精灵准备工具捆绑在
```
tools/
```
目录下；请勿依赖旧的根目录编译二进制文件。

Notes For Codex

给Codex的提示

If the user types

/eggs

or asks to spawn the companion, do the start action immediately and briefly report whether it launched. If the user asks to change companion state, run the

state

command with the closest matching state name. Do not open or explain the script unless launch fails.

如果用户输入

/eggs

或请求生成助手，请立即执行启动操作，并简要报告是否启动成功。如果用户要求更改助手状态，请使用最匹配的状态名称运行

state

命令。除非启动失败，否则不要打开或解释脚本。