fc9f5d554e
Importing an animated pet required a file that was exactly 1536x2288, laid out as 88 seamless cells, with the last two rows holding sixteen distinct gaze angles. No image model emits that. Whatever a user got back from Jimeng or ChatGPT was some fixed size like 1024x1536, so the path ended at "the animation atlas must be exactly 1536x2288 pixels" every time. The third card was worse: "AI-generate full animation" was hardcoded `disabled`, so the one entry point named after what people actually wanted to do was dead. The fix was already in the tree. `scripts/assemble-generated-pet-atlas.py` landed in the same commit as the four built-in pets, which is to say the built-ins were produced this way — it takes an action sheet at any size, slices it on an 8x9 grid, fits each cell to 192x208, mirrors the run row to make run-left, and reuses rows to reach eleven. That capability was never wired to anything a user could reach. `petAtlasNormalize.ts` reimplements it on a canvas in the renderer, so an author draws nine rows and the app derives the rest. Verified against the reference assembler by reversing dada-code's atlas into a nine-row sheet and re-normalizing it: every difference lands on semi-transparent antialiased edges (2314 pixels, max channel delta 14/255) and opaque regions are identical. That residue is canvas premultiplied-alpha round-tripping, not a slicing bug. Three contract details worth stating. Row frame counts are now derived from `PET_ANIMATION_DEFINITIONS` rather than typed out a fourth time; they come out equal to the assembler's `(6,8,8,4,5,8,6,6,6,8,8)`. A sheet already at 1536x2288 passes through byte-for-byte instead of being resliced, because resampling finished artwork buys nothing. And since the validator never inspects the alpha channel, a flattened white background used to import happily and render as a rectangle on the desktop — the renderer now rejects sheets whose atlas is under 5% transparent (the built-ins sit near 78%) with a message that names the actual problem. The copy stops describing the implementation. "Animate one image" and "Import professional animation atlas / exact 1536x2288 v2 PNG" become "use a picture you already have" and "I already have an action sheet"; the dead AI card becomes a three-step walkthrough carrying a copyable prompt, a labelled 8x9 reference grid that can be saved locally, and the checks that catch the common failures. Reference images are generated by a script rather than hand- placed, in both languages. All five locales move together. Caught while reviewing the real dialog in Electron: after finishing the walkthrough the form heading fell through to the atlas branch and announced "I already have an action sheet" to someone who had just been walked through drawing one. Covered by a test now. Not done: docs/images/desktop_ui/15_pet_create_methods.png still shows the old dialog and needs a fresh capture from a running app to match the styling of the shots around it.
10 KiB
Claude Code Haha Desktop 快速上手
这篇指南从安装后的第一次打开开始，带你完成服务商配置、创建会话、审阅代码和查看后台任务。建议先用「询问权限」完成一轮小任务，再逐步启用 Auto、H5 或 Computer Use。
一、首次启动：先让一个模型可用
打开「设置 → 服务商」。桌面端提供两类接入方式。
官方登录
不想手动填写 API Key 时，可以选择：
- Claude 官方：浏览器登录 Claude.ai。
- ChatGPT 官方：通过 OpenAI OAuth 登录。
- Grok 官方：通过 xAI OAuth 登录。
授权完成后回到桌面端，再从模型选择器中选择账号实际开放的模型。模型目录会随账号和服务端能力变化；文档中出现某个模型名称，不代表所有账号都一定可用。
API 服务商
使用 API Key 时：
- 从内置预设中选择服务商；常用预设随桌面端提供，不依赖临时的远程列表。
- 填写 API Key 和 Base URL。
- 确认 API 格式与鉴权方式：
- Anthropic Messages
- OpenAI Chat Completions
- OpenAI Responses
- 核对主模型及 Haiku、Sonnet、Opus 等角色模型映射。
- 先测试连接，成功后再保存并设为默认服务商。
不在预设中的服务可以使用 Custom。不要把 API Key、OAuth 凭证或完整设置文件贴到公开 Issue。
当前内置能力包括 Claude 官方模型目录、OpenAI GPT-5.6 系列、Grok 官方模型，以及 Kimi Code K3 等预设。它们的上下文、thinking 和 effort 支持以当前服务商返回的能力为准。
二、创建第一条会话
-
点击侧边栏的新建按钮，或按
Ctrl/Cmd + N。 -
选择真实的项目目录。Agent 的文件搜索、Git 状态、Diff 和工具操作都会以它为边界。
-
选择模型、思考强度和权限模式。
-
输入一个结果可验证的小任务，例如：
先阅读这个项目的 README 和 package.json，告诉我本地开发如何启动。不要修改文件。 -
观察流式回复、工具调用和权限请求。需要停止时按
Ctrl/Cmd + .。
每个标签对应一个会话。正在运行、失败和空闲状态会显示在标签或会话列表中；关闭仍在运行的标签前，桌面端会要求确认。
三、选择正确的权限模式
桌面端提供五种会话权限模式。
| 模式 | 行为 | 建议场景 |
|---|---|---|
询问权限 (default) |
工具执行前逐项询问 | 第一次进入项目、陌生仓库、风险不明确 |
接受编辑 (acceptEdits) |
自动允许文件编辑，其他操作仍询问 | 已确认修改范围，仍希望审查命令 |
自动模式 (auto) |
Claude 审查工具调用，执行其认为安全的操作并阻止高风险操作 | 熟悉项目后减少重复审批 |
计划模式 (plan) |
只研究和规划，不执行修改 | 先评审方案、做只读调查 |
跳过全部 (bypassPermissions) |
跳过所有权限检查 | 仅限完全可信、可恢复的隔离环境 |
第一次启用自动模式会显示风险确认。Auto 能减少权限询问，但分类并不等于绝对安全；仍应限制工作目录、检查 Diff，并保留版本控制或备份。
跳过全部的风险高于 Auto。不要在含生产凭证、个人资料或不可恢复数据的目录中使用。
活跃任务运行期间不能切换权限模式。请先等待当前轮结束或主动停止，再修改模式。
四、对话、附件与长内容定位
输入与附件
Enter默认发送，Shift + Enter换行；也可以在通用设置中改为Ctrl/Cmd + Enter发送。- 输入
/打开斜杠命令。 - 输入
@搜索并引用工作区文件。 - 可粘贴图片、拖入文件或通过文件选择器添加文件、目录和 PDF。
- 聊天中的本地附件可以用系统默认应用打开，或从「打开方式」中选择外部应用。
附件内容会随会话恢复。若原文件已经移动、删除或当前系统无法访问，打开操作会给出失败提示；这不代表历史消息被删除。
查找与导航
Ctrl/Cmd + F：在当前页面或长对话中查找，并在匹配项之间跳转。- 对话导航：从用户消息和 AI 回复生成目录，适合快速回到长任务的关键节点。
- 消息操作：复制或从某条消息分叉，触屏 H5 中也会保持可发现。
侧边栏的会话搜索、对话内查找和工作区文件搜索是三种不同入口：一个找会话，一个找当前对话内容，一个找项目文件。
五、在工作区审阅改动
打开右侧工作区后，可以：
- 浏览 Git 工作区与变更文件。
- 搜索尚未在目录树中展开的文件；正式桌面安装包已内置对应平台的 ripgrep。
- 预览文本、图片和常见文件。
- 在 Diff 中切换文件，查看旧行、新行和语法高亮。
- 点击单行添加评论，或按住
Shift选择同一侧的连续行。 - 把评论和代码引用带回聊天输入框，让 Agent 根据明确位置继续修改。
被拒绝的 Write/Edit 不会因为工具“尝试过”就算作真实文件变更。最终仍应以磁盘内容和 Git Diff 为准。
六、查看任务、SubAgent 与团队
当会话启动 Task、后台任务、SubAgent 或 Agent Team 后，活动面板会集中展示状态。
- 运行中的 SubAgent 可以立即打开，不必等到结束。
- 详情会继续刷新运行记录和工具调用。
- 后台任务支持停止，并区分完成、失败与已停止。
- 完全退出再启动后，已经持久化的终态不会被简单恢复成“进行中”。
短暂的轮询失败可能只影响面板刷新，不等于任务数据已经丢失。遇到持续异常时，先刷新，再到「设置 → 诊断」收集信息。
七、安装技能与管理 Agent
技能市场
从技能市场可以搜索、筛选、查看来源与安全提示，并安装支持的第三方技能。安装前应阅读技能内容、来源和免责声明；技能本质上可能扩大 Agent 可执行的工作流。
Agent 管理
进入「设置 → Agents」可以：
- 查看内置、用户、项目、插件、策略和 CLI 参数等来源。
- 判断同名 Agent 当前哪个定义生效、哪个被覆盖。
- 创建、编辑或删除用户级和项目级 Agent。
- 为每个 Agent 分别配置模型、思考强度、允许工具和系统提示词。
用户 Agent 写入 ~/.claude/agents/，项目 Agent 写入当前项目的 .claude/agents/。内置、插件与策略来源保持只读。
模型和 effort 可以继承主会话，也可以单独指定；不受所选模型支持的 effort 可能被降低或忽略。完整规则见多 Agent 使用指南。
八、使用桌面宠物
按下面的顺序即可开始使用：
- 进入「设置 → 宠物」。
- 从搭搭 Dada、弧弧 Huhu、补补 Bubu、回回 Huihui 中选择一个内置角色。
- 打开「显示桌面宠物」，透明悬浮窗口会立即出现。
- 按需要调整 96–192px 大小、动画和「显示运行中的任务面板」。
- 在桌面上拖动宠物调整位置；单击宠物会唤起主窗口，单击任务行会返回对应会话，右键可以关闭宠物。
任务面板只显示正在工作、等待处理或失败的活跃任务；没有活跃任务时会自动隐藏。右键关闭宠物不会停止正在执行的任务，下次可以回到「设置 → 宠物」重新开启。
还可以通过「添加宠物」做一只自己的：用一张透明 PNG / WebP 现成图，或按弹窗里的提示词让任意画图 AI 生成一张动作表再选进来（尺寸会自动对齐）。全程在本地完成，不会调用当前聊天模型，也不消耗对话额度。提示词、动作表模板、图片要求和故障排查见桌面宠物使用指南。
宠物仅在 Electron 桌面端运行，不会出现在 H5 页面中。窗口置顶、拖动与多显示器行为仍受操作系统窗口管理影响。
九、从手机或 IM 继续使用
H5
在「设置 → H5 访问」开启后，桌面服务会提供带 Token 的二维码和连接地址。普通局域网访问使用同一个 H5 页面、REST API 和 WebSocket 服务；需要稳定书签或反向代理时可固定端口。
H5 会暴露当前桌面服务的核心能力，只应在可信网络和自己的代理中使用。详细步骤见H5 访问。
IM
「设置 → IM 接入」支持：
- 微信
- 钉钉
- Telegram
- 飞书
扫码绑定平台账号并不等于授权所有联系人。用户仍需发送一次性配对码，或被加入允许列表。详见IM 接入总览。
十、快捷键
| 快捷键 | 功能 |
|---|---|
Ctrl/Cmd + N |
新建会话 |
Ctrl/Cmd + F |
当前页面或对话内查找 |
Ctrl/Cmd + K |
打开全局会话搜索 |
Ctrl/Cmd + . |
停止当前生成 |
Enter |
按当前发送设置发送 |
Shift + Enter |
默认设置下换行 |
/ |
打开斜杠命令 |
@ |
搜索工作区文件 |
Escape |
关闭当前弹层 |