程序员阿江(Relakkes)
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.
14 KiB
桌面端功能详解
本页按用户工作流说明当前桌面端的主要能力和边界。第一次使用建议先读快速上手。
会话与项目
每个会话绑定一个工作目录。桌面端会把会话列表、标签页、模型、权限模式和项目上下文组织到同一个工作台中。
- 新建会话时选择目录、模型、思考强度与权限模式。
- 侧边栏按项目和时间组织历史会话。
- 多标签支持切换、排序和批量关闭。
- 会话恢复会保留已提交的消息、附件上下文、任务终态和阅读位置。
- 异常结束的当前轮可以基于服务端记录的 checkpoint 撤销，不依赖界面猜测文件状态。
如果工作目录已经移动或删除，历史消息仍可阅读，但文件搜索、预览和工具操作会受到限制。
对话与内容导航
对话区支持 Markdown、代码高亮、Mermaid、思考块、工具调用、权限请求和 AI 提问。
长对话
Ctrl/Cmd + F在当前对话中查找，并支持上一个、下一个匹配项。- 对话导航从用户消息和 AI 回复生成可扫描目录。
- 虚拟化长列表会恢复阅读位置，避免重新挂载后直接跳到底部。
- 可以从历史节点继续或分叉任务；最终状态以服务端会话记录为准。
附件
输入框支持粘贴图片、拖放上传和文件选择，可添加图片、普通文件、目录与 PDF。
- 本地附件可以直接用默认应用打开，也可以选择「打开方式」。
- 完全退出或恢复会话后，已经提交的附件仍会作为上下文恢复。
- 文件被移动或删除时，桌面端会报告无法打开，但不会删除历史消息。
- 外部反馈或诊断报告不会主动包含附件正文。
工作区、搜索与 Diff 评审
右侧工作区面向“查看真实文件和审阅改动”，不是聊天消息的装饰视图。
文件与搜索
- 浏览项目目录、Git 状态和变更文件。
- 搜索尚未展开或加载的目录。
- 正式桌面安装包内置对应平台与架构的 ripgrep，不要求用户单独安装
rg。 - 搜索结果可以继续预览或加入聊天上下文。
- 文件不存在、越过工作目录或结果过大时会返回明确状态。
Diff 与评论
- 变更文件按状态展示，并支持在预览标签之间切换。
- Diff 保留旧行、新行和语法高亮。
- 点击一行可添加评论。
- 按住
Shift可选择同一侧连续多行。 - 评论会连同文件路径、行号和代码引用回到聊天输入框。
工具调用被拒绝后，未落盘的 Write/Edit 不应显示成真实变更。交付前仍建议检查 Git Diff。
Browser Preview
工作台可以从「文件」切换到「浏览器」，在应用内预览网页：
- 地址栏支持本地开发地址和普通 HTTPS 页面。
- 「截图」会把当前页面画面带回会话。
- 「选择元素」会把页面元素、选择器和截图作为明确上下文交给 Agent。
- 网页登录态、Cookie 和外部站点权限仍属于敏感数据；公开截图应使用无登录的演示页面。
五种权限模式
| 模式 | 自动执行范围 | 风险提示 |
|---|---|---|
| 询问权限 | 每次工具执行前确认 | 默认且最适合陌生项目 |
| 接受编辑 | 自动批准文件编辑，其他操作仍询问 | 仍需审查命令与外部访问 |
| 自动模式 | 由 Claude 审查工具调用并执行其认为安全的操作 | 不能保证绝对安全，首次启用需确认 |
| 计划模式 | 研究与规划，不执行修改 | 适合先评审方案 |
| 跳过全部 | 跳过所有权限检查 | 只用于完全可信、可恢复的隔离环境 |
同一会话中的多个权限请求会分别保留。活跃轮次期间权限模式保持锁定，避免界面选择与实际运行状态不一致。
服务商、官方登录与模型
「设置 → 服务商」同时覆盖官方账号和 API Provider。
官方登录
- Claude 官方：使用 Claude.ai 账号。
- ChatGPT 官方：使用 OpenAI OAuth，模型目录包括账号实际开放的 GPT 系列。
- Grok 官方：使用 xAI OAuth，支持登录、刷新和动态模型目录。
桌面端会展示当前账号与 Provider 实际返回的模型目录，也支持 Claude、OpenAI、Grok 官方登录和第三方自定义模型。名称出现在目录中不等于当前账号一定拥有调用权限。
API Provider
- 可选 Anthropic Messages、OpenAI Chat Completions 或 OpenAI Responses。
- 内置常用预设，也保留可编辑的 Custom。
- 自定义 Provider 支持主模型和 Haiku、Sonnet、Opus 角色映射。
- 可按模型配置上下文、thinking 和 effort 能力。
- Kimi Code 预设使用 K3 Coding API；具体模型、上下文和鉴权仍以当前预设及服务端为准。
系统代理会按请求目标动态解析，模型请求、OAuth 与适配器不必永久沿用应用启动瞬间的代理结果。代理抖动后仍可能需要等待连接恢复；不要把“支持系统代理”理解成所有代理软件和规则都已完成实机覆盖。
思考强度
模型选择器会根据当前模型与 Provider 显示可用的 effort 档位，并尽量在会话恢复后保留选择。
- 档位可能包括
low、medium、high、xhigh和max。 - 不支持某档的模型可能向下调整或忽略该值。
- effort 不是固定的 thinking token 数。
- 某些模型会强制 required 或 adaptive thinking，优先于通用开关。
技能市场
技能市场提供搜索、筛选、详情、来源、安装状态和安全提示。
- 安装前阅读技能内容和来源。
- 第三方技能可能带来新的工具、脚本或外部依赖。
- 暗色主题和窄窗口下仍可浏览详情。
- 设置页中的技能列表会与市场安装结果同步。
不要仅凭名称安装技能，也不要把实验性技能当作桌面端内置承诺。
Agent 管理
「设置 → Agents」展示内置、用户、项目、插件、策略和 CLI 参数等来源，以及同名定义的覆盖关系。
可编辑范围
- 用户 Agent：对所有项目可用，写入
~/.claude/agents/*.md。 - 项目 Agent：只在当前项目可用，写入
<项目>/.claude/agents/*.md。 - 内置、插件、策略和 CLI 参数来源只读。
每个 Agent 的设置
- 名称、描述与系统提示词。
- 继承或指定模型，包括自定义模型 ID。
- 单独设置 effort。
- 使用全部工具、禁用工具，或选择内置、MCP 与自定义工具规则。
保存成功后，桌面端会尝试刷新当前会话。刷新失败不会回滚已经写入的 Agent 文件；下一次启动仍会重新读取。模型或 effort 是否完整生效取决于最终解析出的 Provider 能力。
完整格式、来源优先级和继承规则见多 Agent 使用指南。
活动、SubAgent 与 Task
会话活动面板汇总：
- 后台任务
- SubAgent
- Task
- Agent Team
- 相关来源和状态
运行中的 SubAgent 可以立即打开，详情会持续刷新执行记录与工具调用。Task 状态会防止旧响应覆盖较新的完成状态；短暂轮询失败时，列表会保留最近的可信数据。
完成、失败和停止等终态会写入会话历史。恢复后仍应以服务端保存的状态为准，而不是只看某次页面刷新。
定时任务
定时任务可以保存提示词、工作目录、模型和 Cron 计划，并查看运行历史或手动触发。当前新建任务固定使用「所有权限」运行，创建表单不会让用户选择权限模式，因此应使用最小范围工作目录并先审查提示词。
定时任务依赖本机桌面服务运行。关机、应用未启动或网络不可用时，不应把它当作云端永久在线调度器。
桌面宠物
「设置 → 宠物」控制 Electron 透明悬浮窗口。选择搭搭、弧弧、补补或回回后，打开「显示桌面宠物」即可使用；大小可在 96–192px 之间调整，也可以单独关闭动画。
- 内置宠物会响应空闲、工作、等待处理和失败状态。
- 空闲时会注视鼠标，鼠标移入会跳跃；单击会挥手并唤起主窗口。
- 可直接拖动宠物改变位置，窗口会在下次启动时恢复；右键选择「关闭宠物」只关闭悬浮窗口，不会停止任务。
- 开启「显示运行中的任务面板」后，可以查看最近的活跃任务并单击返回对应会话；没有活跃任务时面板自动隐藏。
- 关闭任务面板后，有活跃任务时会保留数字角标，单击角标可以再次展开。
添加自己的宠物
点击「添加宠物」，填写宠物 ID、显示名称和描述，再选择做法；三种都可用：
- 用一张现成的图：导入透明 PNG / WebP，由应用在本地添加呼吸、漂浮和任务状态等轻动画。这种宠物不会跑动，也不会跟随鼠标。
- 用 AI 画一只会跑会跳的：弹窗内给出可复制的提示词、对照模板和检查清单，用任意能画图的 AI 产出一张 8 列 × 9 行的动作表，再选进来。
- 我已经有动作图了：跳过教程，直接导入已经画好的动作表或成品图集。
后两种路径导入时会在本地自动切格、缩放对齐、镜像补出向左跑的一帧，因此源图尺寸不必精确；已经是 1536 × 2288 的成品图集会原样保留。
创建成功后，新宠物会自动被选中。自定义宠物保存在本机 ~/.claude/cc-haha/pets（设置 CLAUDE_CONFIG_DIR 时跟随该目录）；当前没有界面内删除按钮，需要通过「打开文件夹」移除对应宠物包后再刷新。
宠物仅在桌面端运行，不在 H5 中显示，也不能直接批准权限或回答交互问题。窗口置顶、拖动与多显示器行为仍受不同操作系统约束。完整图片规格、安全限制与故障排查见桌面宠物使用指南。
IM 接入
「设置 → IM 接入」支持五个平台：
| 平台 | 连接方式 |
|---|---|
| 微信 | 扫码绑定账号 |
| 钉钉 | 扫码或凭证接入 Stream |
| 通过已连接设备扫码 | |
| Telegram | Bot Token |
| 飞书 | App ID / App Secret 与长连接 |
平台账号绑定完成后，实际联系人仍需要一次性配对码或允许列表授权。两者都为空时默认拒绝访问。
发布版桌面端会随本地服务启动 adapter sidecar，并在保存、绑定或解绑后应用新配置。详细平台差异见IM 接入总览。
H5 访问
H5 把当前桌面服务的浏览器界面开放到可信局域网或自己的反向代理。
- H5 页面、REST API 与 WebSocket 可以由同一个服务和端口提供。
- 设置页会生成带 Token 的二维码与连接地址。
- 可配置固定端口和手机断连后的空闲保活时间。
- 手机锁屏或切后台时，正在运行的任务不会因为短暂断连被直接停止；空闲且无人连接后才按保活时间清理。
H5 默认关闭，也不是公开 SaaS。详情见H5 访问。
Computer Use
Computer Use 在获得系统与会话权限后，可以截图、点击和输入。设置页会显示平台、运行环境、依赖和权限状态。
操作系统权限、桌面会话状态和应用可访问性都会影响结果。安装包构建成功不等于当前机器已经完成真实桌面控制验证。使用前请阅读Computer Use 指南。
本地索引与诊断
桌面端使用 SQLite 派生索引加速会话列表、全局搜索、活动统计、定时任务记录和 Trace 读取。
- 原始 JSON / JSONL 会话与设置仍是事实源。
- 索引构建时，界面可以等待或回退到文件读取。
- 索引损坏或部分来源降级时，核心数据不会因为重建索引而删除。
- 「设置 → 诊断」会显示索引状态、数据库/WAL 大小、降级来源和错误代码。
诊断页还可以：
- 查看最近事件和事件 ID。
- 复制错误摘要或经过尽力脱敏的 Issue 报告。
- 导出诊断包、打开日志目录或清理日志。
- 运行 Doctor 检查用户与当前项目状态。
- 只在明确确认后重置可再生的桌面 UI 状态。
Doctor 和安全 UI 重置不会自动修改聊天历史、模型配置、Skills、MCP、IM 或 OAuth。分享任何诊断材料前仍应人工检查隐私内容。
更新与平台边界
正式安装包通过 GitHub Releases 检查更新。更新前应保存未提交工作并完全退出旧版本。
- macOS 正式 Release 使用签名和公证产物。
- Windows 未签名安装包可能显示 SmartScreen；应以当前用户运行，不要主动提升为管理员。
- Windows 覆盖升级包含旧数据识别与恢复保护，但遇到进程占用、来源歧义或复制失败时会停止，而不是猜测迁移。
- Linux 提供 AppImage 与 deb，桌面环境、FUSE 和系统库差异仍可能影响运行。