金乌 Codex 桌宠 v0.1：一只会盯着鼠标看的小太阳神鸟

金乌是一个以中国神话"三足乌 / 太阳神鸟"为原型的 Codex 桌宠实验。当前仓库记录的是 v0.1 第一版代码：它已经包含 Codex 自定义宠物外观包、外部桌宠运行时、设置 UI、鼠标静止互动、分身原型和后续人形态设计提示词。

这一版不是最终形态，而是第一块能跑起来的基座。后续会继续打磨动画、人形态、分身行为、气泡文案和更自然的桌面交互。

版本定位

模块	v0.1 状态
Codex 外观宠物包	已完成
鸟形态 spritesheet	已完成
外部桌宠运行时	已完成原型
设置 UI	已完成原型
鼠标静止互动	已完成原型
分身行为	已完成原型
人形态	已有设计和生成提示词
气泡文案	已有草稿

为什么需要外部运行时

Codex 的"外观 - 宠物"功能主要读取自定义宠物包：

text 复制代码

package/jinwu/pet.json
package/jinwu/spritesheet.webp

这类宠物包负责外观和固定状态动画，但不能直接实现鼠标监听、分身、变身、气泡、躲避等桌面逻辑。

所以 v0.1 采用了双层设计：

Codex 外观包：让金乌能作为 Codex 自定义宠物出现。
外部运行时：用一个独立透明窗口实现鼠标静止互动、分身、朝向鼠标、散开、大小设置等行为。

设置 UI 设计

设置 UI 的目标是：不用命令行，也能控制金乌的主要行为。

双开关

UI 顶部有两个核心开关：

Codex 外观包 ：控制 pet.json + spritesheet.webp 是否作为 Codex 自定义宠物启用标记。
外部互动：控制外部桌宠运行时是否参与鼠标静止、分身、变身和气泡等行为。

这两个开关是分开的。你可以只使用 Codex 外观包，也可以额外启动外部运行时。

允许鼠标接近

早期版本里，鼠标一动金乌就会躲到屏幕边缘，导致用户想靠近它时反而接近不了。

因此 UI 里加入了 允许鼠标接近：

开启时：鼠标移动只会结束围绕和分身互动，金乌不会被吓跑。
关闭时：鼠标移动会触发退避逻辑，本体和分身会散开到屏幕边缘。

这个开关让金乌既能调皮，也不会影响用户正常使用鼠标。

外部宠物大小

UI 提供外部宠物大小滑块。运行时会实时读取配置，并按比例缩放本体和分身。

分身不是简单复制本体。v0.1 里分身会：

比本体更小；
带轻微透明度；
有一圈金色轮廓；
围绕鼠标时面向鼠标；
鼠标移动触发退避时背对鼠标散开。

鼠标静止触发

鼠标静止触发时间可以在 UI 中设置，范围是：

text 复制代码

1 秒 - 10 分钟

默认是 5 秒。达到设定时间后，金乌会进入轻度互动模式：靠近鼠标、看着鼠标、围绕鼠标，必要时生成小分身。

启动与停止

UI 里保留了常用按钮：

刷新：重新读取配置。
启动外部运行时：启动桌面金乌。
停止外部运行时：关闭桌面金乌。
打开配置：打开配置文件目录。
打开宠物目录：打开 Codex 宠物包目录。
退出：关闭设置 UI。注意，退出 UI 不等于关闭运行时。

交互流程

#mermaid-svg-v0dtb0DFsTXPAAzG{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-v0dtb0DFsTXPAAzG .error-icon{fill:#552222;}#mermaid-svg-v0dtb0DFsTXPAAzG .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-v0dtb0DFsTXPAAzG .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-v0dtb0DFsTXPAAzG .marker{fill:#333333;stroke:#333333;}#mermaid-svg-v0dtb0DFsTXPAAzG .marker.cross{stroke:#333333;}#mermaid-svg-v0dtb0DFsTXPAAzG svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-v0dtb0DFsTXPAAzG p{margin:0;}#mermaid-svg-v0dtb0DFsTXPAAzG .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG .cluster-label text{fill:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG .cluster-label span{color:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG .cluster-label span p{background-color:transparent;}#mermaid-svg-v0dtb0DFsTXPAAzG .label text,#mermaid-svg-v0dtb0DFsTXPAAzG span{fill:#333;color:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG .node rect,#mermaid-svg-v0dtb0DFsTXPAAzG .node circle,#mermaid-svg-v0dtb0DFsTXPAAzG .node ellipse,#mermaid-svg-v0dtb0DFsTXPAAzG .node polygon,#mermaid-svg-v0dtb0DFsTXPAAzG .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-v0dtb0DFsTXPAAzG .rough-node .label text,#mermaid-svg-v0dtb0DFsTXPAAzG .node .label text,#mermaid-svg-v0dtb0DFsTXPAAzG .image-shape .label,#mermaid-svg-v0dtb0DFsTXPAAzG .icon-shape .label{text-anchor:middle;}#mermaid-svg-v0dtb0DFsTXPAAzG .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-v0dtb0DFsTXPAAzG .rough-node .label,#mermaid-svg-v0dtb0DFsTXPAAzG .node .label,#mermaid-svg-v0dtb0DFsTXPAAzG .image-shape .label,#mermaid-svg-v0dtb0DFsTXPAAzG .icon-shape .label{text-align:center;}#mermaid-svg-v0dtb0DFsTXPAAzG .node.clickable{cursor:pointer;}#mermaid-svg-v0dtb0DFsTXPAAzG .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-v0dtb0DFsTXPAAzG .arrowheadPath{fill:#333333;}#mermaid-svg-v0dtb0DFsTXPAAzG .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-v0dtb0DFsTXPAAzG .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-v0dtb0DFsTXPAAzG .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-v0dtb0DFsTXPAAzG .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-v0dtb0DFsTXPAAzG .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-v0dtb0DFsTXPAAzG .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-v0dtb0DFsTXPAAzG .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-v0dtb0DFsTXPAAzG .cluster text{fill:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG .cluster span{color:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-v0dtb0DFsTXPAAzG .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-v0dtb0DFsTXPAAzG rect.text{fill:none;stroke-width:0;}#mermaid-svg-v0dtb0DFsTXPAAzG .icon-shape,#mermaid-svg-v0dtb0DFsTXPAAzG .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-v0dtb0DFsTXPAAzG .icon-shape p,#mermaid-svg-v0dtb0DFsTXPAAzG .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-v0dtb0DFsTXPAAzG .icon-shape .label rect,#mermaid-svg-v0dtb0DFsTXPAAzG .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-v0dtb0DFsTXPAAzG .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-v0dtb0DFsTXPAAzG .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-v0dtb0DFsTXPAAzG :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 否
是
否
是
允许接近
不允许接近
打开 Jinwu 设置 UI
配置双开关
外部互动是否开启？
只使用 Codex 外观宠物包
启动外部运行时
读取 jinwu-switches.json
鼠标静止是否达到设定时间？
待机，并持续面向鼠标
靠近鼠标并围绕观察
生成小分身
鼠标移动？
结束围绕，保留本体可接近
本体和分身背对鼠标散开

仓库结构

text 复制代码

config/                         外部运行时配置
docs/                           角色设计、交互设计和公开文档
docs/images/                    README 图片
package/jinwu/                  Codex 自定义宠物包
package/jinwu/runtime-frames/   外部运行时使用的拆帧素材
picture/                        原始视觉素材
prompts/                        后续生成素材提示词
scripts/                        安装脚本、运行时、设置 UI

使用方式

打开设置 UI：

bat 复制代码

scripts\start-jinwu-switch-ui.cmd

直接启动外部运行时：

bat 复制代码

scripts\start-jinwu-runtime.cmd

停止外部运行时：

bat 复制代码

scripts\stop-jinwu-runtime.cmd

安装 Codex 自定义宠物包：

powershell 复制代码

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-codex-pet.ps1

角色设计

金乌当前以鸟形态为主：黑金羽毛、琥珀眼、小火苗冠羽、太阳纹翅膀、圆润 Q 版身体。它不是严肃神明，而是有点傲娇、会观察鼠标、会分身、会小小恶作剧的桌面伙伴。

人形态是后续版本的重要方向。当前仓库已经保留了人形态生成提示词：

text 复制代码

prompts/human-form.md

后续计划让鸟形态和人形态都能分身，并根据当前主形态生成对应分身。

隐私说明

README 和脚本面向公开仓库整理，避免写入本机用户名、个人目录、绝对工作路径等信息。运行时产生的本地状态文件会被 .gitignore 忽略。

仓库链接如下：

c 复制代码

https://github.com/0x78rensai-pixel/jinwu-codex-pet.git

后续计划

补齐人形态素材和变身逻辑。
继续优化朝向与移动动画。
增强气泡系统和文案触发条件。
增加更自然的分身行为。
将外部运行时打包成更易用的桌面程序。
按版本继续发布 v0.2、v0.3。