FAQ / 故障排查

先列高频问题，再列「现象 → 排查」对照表。以下坑全部来自真实开发/实测过程。

高频问题

和 Codex 的宠物模式是什么关系？

灵感与敬意来源。Z-Buddy 是为 ZCode 而生的独立开源实现，宠物包格式参考其开放的精灵图思路（横向分帧、行=状态），并计划兼容，让 Codex 存量宠物生态直接接入。

收费吗？

免费开源（MIT，发布前确定）。唯一的可选成本是未来聊天功能调用 GLM API——用你自己的 Key，费用与本项目无关。

它会读我的代码、上传数据吗？

不上传。插件只把 Agent 状态写入本机 ~/.z-buddy/state.json 和 ~/.z-buddy/events.jsonl，桌宠读取后播放动画，数据全程不出你的电脑。

支持 macOS / Linux 吗？

Windows 优先（10/11 x64）。应用基于 Tauri，跨平台可行，排在 Windows 稳定之后。

现象排查

团子根本没出现

1. 检查应用是否在运行（托盘溢出区找图标，时钟旁 ^ 展开）；
2. 若刚装完：从开始菜单手动启动一次 Z-Buddy；
3. 多显示器用户：团子可能出生在主屏右下角，先找主屏。

团子在，但永远不动（也不睡）

八成是插件没生效。按顺序检查：

1. 插件市场里 z-buddy 是否显示已安装；
2. 是否新建了 ZCode 会话——hook 配置在会话启动时快照，装完不新建会话等于没装（最高频原因）；
3. 团子有「等待审批」以外的静止状态吗？让 ZCode 跑个简单命令（如读文件）试试。

点了团子，ZCode 没停

1. 看团子是否已置灰并显示 ⏸ 角标——没有则暂停未生效；
2. 暂停通过拦截下一次工具调用实现，如果 ZCode 正在长时间执行一个工具，要等这次调用结束后才停；
3. 想放行特定命令：命令文本中包含 .z-buddy/pause 路径的调用会被豁免。

团子拖不动

按住团子身体（不是窗口边缘空白）拖动。位移超过 6px 才会判定为拖拽——这是为了区分「点一下暂停」和「拖走」两种手势。

杀毒软件 / SmartScreen 拦截

个人项目暂未购买代码签名证书，属于已知情况：

• SmartScreen：更多信息 → 仍要运行；
• 第三方杀软误报：把安装目录加入白名单，或先用 Release 里的 SHA256SUMS 核对文件完整性。

状态不对劲 / 显示成别人的会话

多个 ZCode 会话同时运行时，当前版本的状态是「最后写入者胜」（单会话场景设计）。多会话聚合已列入路线图（Phase 2）。

还是不行？

到 GitHub Issues 提一个问题，附上：ZCode 版本、Windows 版本、~/.z-buddy/ 下 state.json 与 events.jsonl 的内容（都是状态数据，不含代码内容）。