ai-pet-helper

ai-pet-helper

将 AI Pet 桌面宠物与 Claude Code / Codex / Cursor 的 agent 生命周期同步，通过 aipet:// 协议自动切换动画。

前置条件

1. 已安装并运行 AI Pet（在 ai-pet 仓库内 pnpm pet:dev，或使用构建后的应用）
2. Node.js ≥ 22（见 package.json 的 engines；hook 由 node 执行）

动画映射

阶段	触发时机	协议
用户提问	UserPromptSubmit	顺序：aipet://running?default=true → aipet://waving?count=1 → aipet://waiting
等待响应	同上（waving 后自动）	aipet://waiting
AI 开始工作	首次 PreToolUse（waiting 阶段）	aipet://jumping?count=1
代码审查	SubagentStart（code-reviewer / review）	aipet://review
失败	StopFailure / PostToolUseFailure	先 aipet://text?icon=error&txt=…（有失败文案时），再 aipet://failed?count=3
任务结束	Stop / SessionEnd / TaskCompleted	aipet://text?tl={SESSION_TITLE}&txt={SUMMARY}&sid={SESSION_ID}（本次回复摘要，最多 50 字），随后 aipet://base

text 协议会在三类时机触发：输出过程中由 on-agent-response.mjs 按增量更新（Cursor afterAgentResponse / Claude MessageDisplay）；工具/API 失败时由 on-tools-failed.mjs / on-failed.mjs 推送错误摘要（先 text 再 failed）；任务结束时由 on-base.mjs 发送最终摘要并恢复 base（先 text 后 base）。tl 取自用户首次提问（on-user-prompt.mjs 写入 sessionTitle），sty 为会话类型（claude / codex / cursor / qcode），sid 为会话 sessionId，txt 为摘要（最多 50 字符，中文按 1 字计）。失败摘要由 libs/resolve-failure.mjs 从 hook stdin 的 error_message / error / message 等字段拼接。回复文本按 hook 字段 → 状态缓存 → transcript 解析；sessionId / transcriptPath / sessionTitle 持久化在 ~/.ai-pet/plugin-state.json。

Cursor 事件对应（hooks/hooks-cursor.json）

Claude / Codex	Cursor	脚本
UserPromptSubmit	beforeSubmitPrompt	utils/on-user-prompt.mjs
SessionStart	—	utils/on-session-start.mjs
PreToolUse	preToolUse	utils/on-state-switch.mjs
SubagentStart（review）	subagentStart	utils/on-review.mjs
PostToolUseFailure	postToolUseFailure	utils/on-tools-failed.mjs
StopFailure	—	utils/on-failed.mjs
MessageDisplay	—	utils/on-agent-response.mjs
—	afterAgentResponse	utils/on-agent-response.mjs
Stop / TaskCompleted	stop	utils/on-base.mjs
SessionEnd	sessionEnd	utils/on-base.mjs

Cursor 无 StopFailure 独立事件；工具失败由 postToolUseFailure 触发 on-tools-failed.mjs（失败时先发 aipet://text 再播 failed）。命令路径相对插件根目录。

安装（未上架市场，需手动安装）

在本仓库根目录：

node scripts/install-plugin.mjs              # Claude Code + Codex（默认）
node scripts/install-plugin.mjs --claude     # 仅 Claude Code
node scripts/install-plugin.mjs --codex      # 仅 Codex
pnpm install-plugin                          # 同上（package.json script）

Windows：若出现 EPERM 无法创建符号链接，安装脚本会自动尝试目录联接（junction / mklink /J）。仍失败时可开启系统「开发人员模式」，或以管理员运行终端。

claude plugin install 若因 EPERM 失败，多为 Claude 在缓存里复制了带 node_modules 的完整仓库。可重启 Claude 使用（若已 enabled），或开发时用 claude --plugin-dir /path/to/ai-pet-helper 临时加载。

install-plugin 会：

1. 将本包链接到 ~/.ai-pet/plugins/ai-pet-helper（Unix 为符号链接，Windows 为联接）
2. 注册本地市场 ai-pet-marketplace（~/.ai-pet/marketplace/ai-pet-marketplace → 本包根目录，含 .claude-plugin/marketplace.json）
3. 调用 claude / codex CLI 安装并启用 ai-pet-helper@ai-pet-marketplace

预览步骤、卸载：

node scripts/install-plugin.mjs --dry-run
node scripts/install-plugin.mjs --uninstall    # 卸载（install 的逆操作）
node scripts/install-plugin.mjs --uninstall --claude
pnpm remove-plugin                             # 同上（转发至 install-plugin --uninstall）

构建（同步各 IDE 插件清单字段）：

pnpm build

单元测试：

pnpm test

前置条件：目标 CLI（claude 或 codex）在 PATH 中。Codex 安装后需重启；Claude Code 建议新开会话。

临时加载（不写入配置）

claude --plugin-dir ~/.ai-pet/plugins/ai-pet-helper

需先执行 install-plugin 或手动 ln -sf 到 ~/.ai-pet/plugins/ai-pet-helper。插件需包含 .claude-plugin/plugin.json、hooks/hooks.json（Codex 使用根目录 hooks.json）。

手动测试

node utils/on-user-prompt.mjs
node utils/on-state-switch.mjs
node utils/on-review.mjs
node utils/on-tools-failed.mjs
node utils/on-failed.mjs
node utils/on-agent-response.mjs
node utils/on-base.mjs

配置目录

与 AI Pet 共用 ~/.ai-pet/：