yui-local-pet

Yui 是一个 Windows 本地桌面宠物。她以透明、无边框、置顶的小窗口显示在桌面上，播放轻量动画，并通过外部 agent 的官方 hook 接收状态信号，在 Codex、Claude Code、Kimi Code 工作时切换到对应状态。

Yui 本体保持轻量：日常只运行 yui.exe。集成安装、修复、卸载和检查放在单独的 yui-manager.exe 中，需要时再运行。

Portable 使用方式

推荐的 portable 包包含三个可执行文件：

• yui.exe：桌面宠物本体，日常运行它。
• yui-hook.exe：原生 hook bridge，供 Codex / Claude Code / Kimi Code 调用；用户通常不直接运行。
• yui-manager.exe：集成管理工具，用于检查、安装、修复或卸载 agent 集成。

构建 portable 文件夹：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-portable.ps1

输出目录是 portable\yui\，其中包含 yui.exe、yui-hook.exe 和 yui-manager.exe。

集成管理工具

查看当前集成状态：

.\yui-manager.exe status
.\yui-manager.exe status --json

安装或修复集成：

.\yui-manager.exe repair all
.\yui-manager.exe repair codex
.\yui-manager.exe repair claude
.\yui-manager.exe repair kimi

只卸载 Yui 自己写入的集成：

.\yui-manager.exe uninstall all

双击无参数运行 yui-manager.exe 会打开一个轻量 Windows 原生对话框。它会先显示状态，再按 Codex、Claude Code、Kimi Code 分别询问是否安装/修复、卸载或跳过。

除非用户明确运行 install、repair 或 uninstall，否则管理器不会修改任何外部 agent 配置。写入 Codex、Claude Code 或 Kimi Code 配置前，管理器会先创建备份。

管理器会把一份稳定的 yui-hook.exe 复制到：

%LOCALAPPDATA%\yui-local-pet\hooks\yui-hook.exe

agent 配置会指向这个位置。这样即使移动 portable 文件夹，已经安装的 hook 也不会立刻失效。

状态与隐私

Yui 的 hook 事件文件只包含最小状态信息：

{
  version: 1,
  source: "claude-code" | "codex-cli" | "kimi-code",
  event: "session-start" | "running" | "permission" | "question" | "completed" | "failed" | "session-end",
  sessionId: string,
  timestamp: number,
  signal?: string
}

Yui 不会把 prompt 文本、工具参数、工具输出、模型回复或 Obsidian vault 内容写入状态事件。

如果 Yui 没有运行，hook 会快速退出，不阻塞 agent。若 listener.pid 指向已经退出的 Yui 进程，hook 会把这个 stale marker 清理掉。

Codex 集成

Codex 使用用户级配置：

• ~/.codex/hooks.json：生命周期 hook。
• ~/.codex/config.toml：顶层 notify 命令。

Yui 会保留并转发用户原本的 notify 命令，只额外提取 thread id 来写入完成事件。卸载时，只有当前 notify 仍指向 Yui 时才会恢复原命令；后续用户自己改过的配置不会被覆盖。

Codex 已运行的进程不会自动热加载新 hook。安装或修复后，请重启相关 Codex 会话。

Claude Code 集成

Claude Code 使用用户级 ~/.claude/settings.json hooks。Yui 会保留已有设置和非 Yui hook，只追加或替换自己管理的 hook。

支持的状态包括：

• 运行中
• 权限请求
• 用户回答请求
• 完成
• 失败
• 会话结束

Kimi Code 集成

Kimi Code 使用 ~/.kimi-code/config.toml 中的 [[hooks]] 配置。Yui 会保留已有设置和非 Yui hook，只追加或替换自己管理的 hook。

Kimi Code hook 到 Yui 事件的映射：

• SessionStart -> session-start
• UserPromptSubmit / PreToolUse / PostToolUse -> running
• PermissionRequest -> permission
• Stop -> completed
• StopFailure -> failed
• SessionEnd -> session-end

Kimi Code 目前没有独立的用户提问 hook，因此 Yui 的 question 状态通常不会由 Kimi Code 触发。

Claudian 兼容性

Yui 不修改 Claudian、Obsidian 或 vault 文件。Claudian 兼容性只依赖它底层所使用的 Claude Code 或 Codex 后端暴露出的生命周期信号。

• Claude Code 后端：可获得运行、权限请求、回答请求、完成和失败等状态。
• Codex 后端：完成状态主要依赖 Codex 的 agent-turn-complete notify 信号；其他状态取决于 Claudian 启动的后端是否暴露 hook。

不要通过修改 Claudian 插件源码来补信号。若外部安全接口拿不到某个状态，应把它记录为限制。

Legacy PowerShell 脚本

下面这些旧 PowerShell 安装器保留用于开发和迁移参考。新安装优先使用 yui-manager.exe，因为它写入原生 yui-hook.exe 命令，hook 运行时不再依赖 Node.js。

安装 Claude Code legacy hooks：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-claude-hooks.ps1

卸载 Claude Code legacy hooks：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\uninstall-claude-hooks.ps1

安装 Codex legacy hooks：

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

卸载 Codex legacy hooks：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\uninstall-codex-hooks.ps1

安装 Kimi Code legacy hooks：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-kimi-hooks.ps1

卸载 Kimi Code legacy hooks：

powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\uninstall-kimi-hooks.ps1

开发验证

常用检查：

npm.cmd run build
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-native-integration.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-codex-hooks.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-claude-hooks.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-kimi-hooks.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-yui-listener-check.ps1
Set-Location .\src-tauri
cargo test

这些测试必须使用隔离临时目录，不得把真实插件目录、Obsidian vault 或用户数据目录作为测试源或目标。

交互行为

• 透明无边框窗口。
• 始终置顶。
• 不显示任务栏图标。
• 可拖动位置。
• 双击或右键可退出。
• 空闲和运行态都使用低频动画调度，避免高频渲染循环。