Skip to content

USAGE.md

Latest commit

 

History

History
327 lines (220 loc) · 9.18 KB

USAGE.md

File metadata and controls

327 lines (220 loc) · 9.18 KB
Raw

TermiPet 使用指南

这份指南面向第一次使用 TermiPet 的用户，按「启动应用 → 授权 → 日常使用 → 个性化配置 → 排查问题」的顺序介绍。

1. 启动 TermiPet

如果你是在项目源码目录中使用，运行：

zsh Scripts/build-plugin.sh

构建完成后，应用会自动启动。TermiPet 是菜单栏应用，不会出现在 Dock 中；启动后你会在 macOS 菜单栏看到一个小图标。

菜单栏里可以做这些事：

  • 显示宠物。
  • 打开设置。
  • 请求辅助功能授权。
  • 打开辅助功能设置。
  • 安装或卸载 Claude Code Hook。
  • 退出 TermiPet。

2. 授予辅助功能权限

首次使用建议先授权辅助功能权限，否则终端预览和快捷输入可能不可用。

操作步骤：

  1. 点击菜单栏 TermiPet 图标。
  2. 点击 请求辅助功能授权。
  3. 再点击 打开辅助功能设置。
  4. 在 macOS 系统设置中找到 TermiPet，并打开开关。
  5. 如果系统没有立即生效，退出并重新启动 TermiPet。

授权后，TermiPet 才能识别当前终端窗口、读取部分终端文本，并向终端输入快捷指令。

3. 基本操作

移动宠物

按住宠物本体拖动即可移动位置。宠物窗口会悬浮在屏幕上，并可出现在所有桌面空间。

打开工具按钮

把鼠标移到宠物上方，会出现工具按钮。

常用按钮：

图标含义 用途
终端 打开快捷指令面板
文件夹 选择文件夹并输入 cd
对话 和宠物聊天
调色板 切换皮肤
计时器 开始、暂停或继续番茄钟
停止 停止番茄钟
杯子 开始 5 分钟休息

手动触发动作

工具按钮下方有一排表情动作按钮。点击后，宠物会临时播放对应动作，例如运行、开心、提醒、错误、睡觉、思考、庆祝等。

右键菜单

右键宠物可以打开：

  • 设置...
  • 关闭宠物

4. 使用快捷指令

  1. 先聚焦一个终端窗口。
  2. 把鼠标移到宠物上。
  3. 点击终端按钮打开快捷指令面板。
  4. 点击某条指令，TermiPet 会把指令输入到最近的目标终端中。

内置指令主要面向 Claude Code，包括：

  • claude
  • claude --enable-auto-mode
  • claude --dangerously-skip-permissions
  • /compact
  • /init
  • /clear
  • /memory
  • /model
  • /help
  • /review
  • /status
  • /diff
  • /cost
  • /login
  • /config
  • /mcp
  • /doctor
  • /terminal-setup

添加自定义指令

  1. 打开 设置 → 快捷指令。
  2. 点击 添加。
  3. 填写标题、实际输入文本和说明。
  4. 保存后即可在快捷指令面板中使用。

你也可以在设置中置顶指令、拖拽排序，或删除自定义指令。内置默认指令不能删除。

5. 使用文件夹快捷入口

点击文件夹按钮后，选择一个项目文件夹。TermiPet 会把对应的 cd 命令输入到目标终端中，适合快速切换工作目录。

如果没有成功输入，请检查：

  • 是否已经聚焦过一个终端。
  • 是否授予辅助功能权限。
  • 终端是否允许当前应用输入内容。

6. 查看终端和 Agent 状态

当你聚焦终端、编辑器、AI 对话或 Claude Code 正在运行时，宠物上方可能出现状态卡片。

卡片可能显示：

  • 当前终端名称和窗口标题。
  • 终端输出摘要。
  • 当前编辑器或项目提示。
  • Claude Code 是否正在思考、调用工具、等待授权、压缩上下文或已经完成。

如果卡片提示需要辅助功能权限，请按本指南第 2 节授权。

7. 安装 Claude Code Hook

Hook 可以让 TermiPet 更准确地显示 Claude Code 状态。

安装步骤：

  1. 点击菜单栏 TermiPet 图标。
  2. 点击 安装 Claude Code Hook。
  3. 看到安装成功提示后，重启正在运行的 claude 进程。
  4. 重新开始 Claude Code 会话后，宠物上方会显示更准确的状态。

Hook 会写入：

~/.claude/hooks/floating-pet-hook.sh
~/.claude/hooks/floating-pet-port
~/.claude/settings.json

首次安装时会尽量备份原设置：

~/.claude/settings.json.floating-pet.bak

不想继续使用时，可以在菜单栏点击 卸载 Claude Code Hook。

8. 和宠物聊天

点击对话按钮即可打开聊天框。第一次聊天前，请先配置模型。

使用本地 Ollama

  1. 安装 Ollama。
  2. 打开 设置 → 模型。
  3. 选择 本地模型。
  4. 如果 Ollama 未启动，点击 启动 Ollama。
  5. 下载推荐模型，或下载其他模型。
  6. 选择已下载模型。
  7. 点击 保存配置。

推荐优先尝试 Qwen2.5 1.5B，体积不大，中文效果也比较稳。

使用线上 API

  1. 打开 设置 → 模型。
  2. 选择 线上 API。
  3. 选择 OpenAI、Google Gemini 或自定义 API。
  4. 填写 API Key、Base URL 和模型名。
  5. 点击 读取模型，如果服务支持模型列表，会出现可选模型。
  6. 点击 测试连接。
  7. 测试成功后点击 保存配置。

API Key 保存在 macOS 钥匙串中。自定义 API 需要兼容 OpenAI Chat Completions 格式。

9. 调整宠物性格

打开 设置 → 性格，可以配置：

  • 宠物名称。
  • 主人名字。
  • 性格预设。
  • Prompt。
  • 额外约束条件。

预设适合快速开始：

预设 适合场景
开心 想要轻松、积极的陪伴
编程搭子 希望宠物围绕开发状态给建议
温柔教练 压力较大时做稳定陪伴
专注提醒 需要减少分心、推进任务
慵懒 想要短句、低能量风格
元气 想要强烈鼓励和活力
睿智 想要简短、有判断的反馈
毒舌 想要带一点辛辣幽默
自定义 完全自己写 Prompt

如果你给宠物添加约束，例如「只说中文」「回答不超过三句话」，宠物聊天时会尽量遵守。

10. 使用番茄钟

点击计时器按钮开始 25 分钟工作计时。运行中再次点击可以暂停或继续。

番茄钟运行时：

  • 宠物上方会显示倒计时。
  • 点击停止按钮可结束计时。
  • 点击杯子按钮可直接开始 5 分钟休息。
  • 计时完成时，宠物会播放庆祝动作。

11. 切换皮肤和语言

皮肤

点击工具栏调色板按钮可以快速循环切换皮肤。也可以打开 设置 → 皮肤 手动选择。

当前支持：

  • 玻璃风格。
  • 暗色风格。
  • 像素风格。

语言

打开 设置 → 语言 可以切换界面语言。语言切换需要重启应用后完整生效。

12. 导入宠物资源包

打开 设置 → 宠物，点击选择或导入宠物文件夹。

宠物文件夹必须包含：

pet.json
spritesheet.webp

pet.json 中的 spritesheetPath 必须指向真实存在的图片文件。导入后，TermiPet 会复制一份到 Application Support 目录，因此原文件夹之后移动或改名通常不会影响已导入的宠物。

13. 查看 AI 用量

鼠标悬停宠物时，TermiPet 会尝试读取 Claude Code、Codex、GitHub Copilot 的用量数据，并显示在 AI 用量卡片中。

常见状态：

状态 含义
已同步 读取成功
待读取 尚未刷新
需登录 对应服务登录信息过期
未登录 未检测到登录信息
错误 读取或解析失败

点击卡片右上角刷新按钮可以手动重新读取。

14. 常见问题

宠物没有出现在屏幕上

点击菜单栏 TermiPet 图标，再点击 显示宠物。如果仍然没有出现，可以退出后重新运行构建脚本或重新打开 App/TermiPet.app。

点击快捷指令没有输入到终端

请检查：

  • 是否已经打开并聚焦过终端窗口。
  • 是否授予辅助功能权限。
  • 目标终端是否被系统安全设置阻止。
  • 当前是否有输入框或其他应用抢占焦点。

终端预览一直提示无法读取

通常是辅助功能权限没有生效。进入系统设置重新开启 TermiPet 权限，然后重启应用。

本地模型显示未检测到

请确认：

  • Ollama 已安装。
  • Ollama 正在运行。
  • 模型已经下载完成。
  • 设置页点击过 重新检测。

线上 API 测试失败

请检查：

  • API Key 是否正确。
  • Base URL 是否包含正确版本路径，例如 OpenAI 常用 /v1。
  • 模型名是否存在且当前账号有权限。
  • 自定义 API 是否兼容 OpenAI Chat Completions。
  • 网络代理或防火墙是否拦截请求。

Claude Code 状态不更新

请检查：

  • 是否安装了 Claude Code Hook。
  • 安装 Hook 后是否重启了 claude 进程。
  • TermiPet 是否正在运行。
  • ~/.claude/settings.json 中是否保留了 TermiPet Hook 配置。

重建后辅助功能权限丢失

构建脚本会优先使用本地自签证书 TermiPetLocal，尽量保持权限稳定。如果签名失败回退到 ad-hoc 签名，macOS 可能要求重新授权。重新授权一次即可。

15. 开发者日常验证

如果你修改了代码或资源，请务必运行：

zsh Scripts/build-plugin.sh

脚本会自动测试、构建、签名并启动 APP。应用启动后，请在界面上确认改动确实生效，再认为本次修改完成。