HaoPlanAPI 用户使用手册

1. 软件能做什么 #

HaoPlanAPI 桌面端把「跑 AI」这件事做成了开箱即用:

• 🔐 集中管理 API Key:创建、停用、查配额、查消耗,一处搞定
• 💬 AI 聊天:内置聊天界面,支持 OpenAI / Anthropic / Gemini 等几十种模型,带 Markdown 渲染、代码高亮、图片附件
• 🎨 AI 作图:DALL·E、GPT Image、Nano Banana、Midjourney 等图像模型一站式,生成的图自动落盘可查可下
• 🛠️ CC 配置:一键把网关 Key 写入 Claude Code / Codex / Gemini CLI / Cursor / OpenCode 等 7 种本地编辑器
• 📦 工具环境:Node.js / Git / Homebrew 等基础依赖检测 + 一键安装,新手向导带路
• 💰 平台充值 · 使用记录:支付宝/微信/信用卡 直接充,token 消耗实时可查

一句话:让"会用 AI"这件事的入门成本降到 5 分钟以内。

2. 首次启动 · 登录 #

启动 APP 后会先看到登录页:

操作要点:

1. 输入邮箱和密码
2. 没账号?点右下角「注册账号」会跳到官网 api.haoplan.net,注册完回来登录
3. 登录成功后 token 写入本地 ~/.haoplanapi/auth.json,下次启动免登录

💡 忘记密码:目前要去官网走重置流程,APP 内不提供

3. 新手引导 — 5 分钟跑通全流程 #

登录后,侧边栏顶部第一项是「🎓 新手引导」,未完成必经步骤时旁边有橙色小红点。控制台顶部也会显示「👋 距离上手只差 N 步」的提示卡。

引导一共 8 步,顶部有进度条,每步分必经和推荐/可选:

每张卡片可点「详情 ▾」展开,显示「是什么 / 为什么需要 / 怎么操作」三段说明:

完成所有必经后会出现 🎉 完成横幅:

3.1 在场者横幅 — 跳到对应页后的「贴身」指引 #

从引导卡片点「立即前往 →」(或控制台「下一步」卡片的同名按钮)后,目标页顶部会自动弹出一条紫色横幅,列出该页的 3-4 条具体操作要点(点哪里、注意什么):

完成对应动作后(例如创建一个 Key、发一条聊天),横幅自动变绿显示 🎉 并提示「前往下一步」:

• 横幅可点「×」暂时隐藏(从引导页再次进入会重新出现)
• 直接从侧边栏点进页面(不走引导)→ 不会弹横幅,不打扰熟手
• 横幅文案与新手引导页的「怎么操作」一段同源 —— 改一处,两处同步

💡 小贴士

• 推荐/可选步骤可以「跳过」,跳过后还能「取消跳过」
• 真实数据(已创建的 Key、聊天记录)会自动反推完成状态,不需要手动打勾
• 底部有「重置进度」按钮,不会动你的数据,只清空引导状态
• 不想要引导?系统设置 → 应用偏好 → 新手引导 一键关掉,侧边栏入口、控制台提示卡、所有横幅都消失

4. 主界面与侧边栏 #

侧边栏自上而下:

┌─ 🎓 新手引导    ← 新用户优先看
├─ 🏠 控制台      ← 余额、API Key 概览
├─ 💬 AI 聊天
├─ 🖼️ AI 作图
├─ 🔑 API 密钥
├─ 🧊 模型分组
├─ 📊 使用记录
├─ 💰 平台充值
├─ 💻 CC 配置
├─ 🛠️ 开发工具
└─ ⚙️ 系统设置

操作要点:

• 点 logo 可折叠侧边栏(收成小图标),给主区让出空间
• 左下角显示当前登录账户邮箱
• 右上角顶部显示账户余额 + 刷新按钮

5. 控制台 — 余额与概览 #

进入 APP 后默认页:

包含模块:

1. 顶部卡片:账户余额(美元),刷新按钮
2. 「下一步」提示卡(条件显示):还有未完成的引导步骤时出现
3. 统计四宫格:API Key 总数 / 活跃数 / 跳「AI 聊天」/ 跳「AI 作图」
4. 最近 Key 列表:最近 3 个 Key 的状态摘要
5. 快捷操作 + 账户信息

💡 余额是后端真实数值,如果你充了钱但没显示,点刷新按钮强制拉取一次

6. API 密钥 — 创建你的第一把钥匙 #

侧边栏点「API 密钥」:

创建新 Key:

1. 点右上角「+ 新建 Key」
2. 填表:
   • 名称:给 Key 取个识别用的名字 (例如 my-mac-claude-code)
   • 分组:选择平台分组 (决定能用哪些模型 + 价格倍率)
   • 配额 (可选):限制单 Key 总消耗,留空就是不限
3. 点「确认」,生成的 Key 只显示一次,请立刻复制保存

⚠️ 重要:Key 一旦生成,完整明文只能在创建那一刻看到,关掉窗口就只剩遮罩显示。如果不小心丢了,只能停用旧的、新建一个

已有 Key 的管理:

• 复制:点行尾的复制图标
• 编辑/停用/删除:点行尾的 ⋯ 菜单
• 配额状态:badge 显示「活跃 / 已停用 / 配额耗尽 / 已过期」
• 消耗:列表里直接显示已用 / 总配额

7. 模型分组 — 看看你能用哪些模型 #

「模型分组」页让你看到账户能用的所有分组及其旗下模型:

左边一栏是分组列表,点一个分组,右边展示该分组下所有模型 + 单价:

💡 创建 Key 之前可以来这里看看哪个分组覆盖你想用的模型 + 价格更划算

8. AI 聊天 #

侧边栏「AI 聊天」:

操作流程:

1. 左边一列:历史会话。点「+ 新建会话」开新对话
2. 右上角:选模型 (按 Key 兼容范围筛选)
3. 输入框:支持
   • 多行 (Shift+Enter 换行)
   • 拖拽图片附件 (Cmd/Ctrl+V 粘贴图片也行)
   • 拖拽 / 粘贴文本文件
4. 回复:支持 Markdown 渲染 + 代码高亮 + 一键复制代码块
5. 会话默认懒加载:打开会话先显示最近 30 条,往上滚自动加载

💡 小技巧

• 同一个会话可以中途切模型,不影响历史
• 会话标题自动用首条消息前 20 字作为标题,也可手动改
• 删除会话不影响后端,只清本地记录

9. AI 作图 #

侧边栏「AI 作图」:

操作流程:

1. 上方选分组 → 模型 (DALL·E 3 / GPT Image 1 / Nano Banana / Midjourney 等)
2. 输入 prompt
3. (可选) 拖入参考图 — 支持的模型才会显示该区域
4. 选尺寸、张数,点「生成」
5. 等 10-60 秒,图自动保存到 ~/.haoplanapi/images/

每张图的右上角四个按钮(置于图片右上角):

💡 小技巧

• 默认显示最近 12 张,往下滚瀑布流加载更多
• 同一 prompt 多次生成会建立画廊,每条记录都能下载/复制/重生成
• 选了「支持参考图」的模型才能拖入参考图,UI 会自动开/关该区域

10. 平台充值 #

侧边栏「平台充值」:

支持的支付方式:

• 支付宝(扫码 / 直跳)
• 微信(扫码 / 直跳)
• 信用卡 (Stripe / Airwallex / EasyPay)

操作:

1. 输入金额(各方式有最低/最高限制)
2. 选支付方式
3. 扫码或跳转
4. 到账通常 < 60 秒,可点控制台刷新按钮验证

⚠️ 出现「白屏 / 无二维码」时,APP 会禁用浏览器跳转避免误付,稍等几秒后会出二维码

11. 使用记录 #

侧边栏「使用记录」:

能看到:

• 时间范围筛选 (今日 / 7 天 / 30 天 / 自定义)
• 按 Key 聚合 / 按模型聚合
• 每次请求的 token 数、生成耗时、金额
• 顶部统计:总调用 / 总消耗 / 平均单价

💡 监控异常消耗的最佳入口。如果某个 Key 突增消耗,这里能立刻定位到哪个模型在烧

12. CC 配置 — 一键接入本地编辑器 #

侧边栏「CC 配置」:

这是把本平台 Key 一键写入本地 AI 编辑器的页面,省去你手动编辑 ~/.claude/settings.json / ~/.codex/config.toml 等等。

支持的编辑器:

操作:

1. 上方 segmented control 选要配的编辑器
2. 下方列出你账户里兼容该编辑器平台的 active Key
3. 点 Key 右侧「应用」 → 自动写配置文件
4. 重启该编辑器即可生效

右上角「一键清理配置」:同时清掉所有编辑器里 APP 写过的 AUTH_TOKEN / BASE_URL,不影响编辑器本身

⚠️ 编辑器配置区显示外部配置(橙色) 时,说明检测到非 APP 写入的凭证,可以点「强制清理」覆盖

13. 工具环境 — 装好 Node / AI CLI #

侧边栏「开发工具」(原工具环境):

包含三块:

13.1 快速打开终端 (顶部) #

点按钮就弹出对应系统终端,不再需要 Cmd+Space → 搜索 Terminal。

13.2 新手向导 #

顶部有总进度条(X / N 步 + 黄→橙→绿色彩),一眼看出还差多少。

按三组分块呈现(基础环境 → AI 工具 → 应用配置),每步带:

• 「必装」/「可选」徽章 —— 必装的标青色,可选灰色
• 「预计耗时」(2 分钟 / 5-10 分钟 / 5-15 分钟)
• 「一键安装」按钮 —— 未装时直接出现;装好后自动隐藏并打绿勾

每步可点「详情 ▾」展开,看到 4 段说明:

例如 Homebrew 的常见报错:

• ⚠ 安装时网络超时 → 换用 USTC/清华镜像,或挂代理
• ⚠ brew 命令找不到 → 装完后重启终端 / 刷新 PATH。Apple Silicon 默认在 /opt/homebrew/bin

13.3 工具卡片 #

每张卡片:

• 未装时:「一键安装」+「复制命令」+「官网下载」
• 已装时:「启动会话 / 常用命令 ▾ / 复制安装命令」
• 有更新:「升级到 vX.Y.Z」

「一键安装」默认行为:弹出系统终端,粘贴命令,自动回车 — 你看得到全部输出,可以输 sudo 密码、看见报错。

💡 进阶:如果你确信不需要看输出,可以在「系统设置 → 应用偏好」开启静默安装 — 应用内静默执行,完成弹 toast。但出错时排查不便,不推荐新手用。

支持的工具目录:

14. 系统设置 #

侧边栏「系统设置」:

含三块:

14.1 API 配置 (只读) #

• 管理 API 地址 (api.haoplan.net/api/v1)
• 网关地址 (用于编辑器的 BASE_URL)
• 本地数据目录 (~/.haoplanapi/)

14.2 应用偏好 #

两个全局行为开关,都默认对新手友好:

⚠️ 关闭新手引导后,/guide 路由本身仍可手动访问(直输 URL 或重新开启) —— 之前的进度也都保留

14.3 账户信息 + 版本检查 #

• 邮箱、角色
• 当前版本 (右上角 logo 旁也显示)
• 「检查更新」按钮:对比 hp-version.haoplan.net/haoplan.json 看是否有新版

15. 常见问题 (FAQ) #

Q1. 启动后白屏 / 报错 #

按 Cmd+Opt+I (mac) / Ctrl+Shift+I (win) 打开 DevTools,把 Console 第一条红色错误截图发给我们。

Q2. macOS 提示「应用已损坏,无法打开」 #

sudo xattr -rd com.apple.quarantine /Applications/HaoPlanAPI.app

或者右键点击应用 → 打开(只需一次),系统会记住允许。

Q3. AI 聊天 / 作图返回「Image generation is not enabled for this group」 #

该分组在后端未启用图像生成。换一个分组的 Key,或联系后台管理员开启。

Q4. 工具环境页一直显示「未安装」,但我装过了 #

• 装好新工具后,APP 不会自动刷新 PATH(进程已启动)。装完点工具页右上角「重新检测」即可。
• 如果还是检测不到,完全退出 APP 再启动(让新 PATH 生效)。

Q5. CC 配置「应用」后编辑器没反应 #

• 重启该编辑器(Claude Code / Codex 等都需要重启读配置)
• 确认 APP 这边显示「已连接」状态,Key 和 Endpoint 都正确

Q6. 引导提示卡总是出现,但我已经会用了 #

• 控制台顶部那张卡片右上角有「×」按钮,点了不再显示(侧边栏入口仍可访问)
• 或者直接进侧边栏「新手引导」,把可选项「跳过」掉,完成 2 个必经后横幅会变成「🎉 完成」
• 想全部隐藏(包括侧边栏入口、控制台卡、所有页面顶部横幅):系统设置 → 应用偏好 → 新手引导 关掉

Q7. 充值后余额没变 #

• 等 1 分钟,然后控制台点余额旁的刷新按钮
• 仍然没变,看「使用记录」是否能看到充值流水
• 都没有,联系客服并提供充值订单号

Q8. 开发工具页 Homebrew / Xcode CLT 显示「已装」但实际我已经卸载了 #

可能是 wrapper 脚本残留:虽然 brew uninstall / 删除安装目录后,/opt/homebrew/bin/brew 这个壳脚本仍然存在,跑 brew --version 还能输出版本号骗过检测。

APP 已经做了双重校验:除了跑 --version,还会检查 /opt/homebrew/Library/Homebrew/brew.rb 等关键文件是否真的存在。如果版本能跑出来但关键文件不在,会自动判为「未装」并在 DevTools Console 留 warn 日志。

如果你认为状态仍然不准:

1. 打开 DevTools (Cmd+Opt+I) 看 Console 有没有 [toolDetector] brew: ... treating as NOT installed
2. 终端 ls /opt/homebrew/Library/Homebrew/brew.rb 看文件是否存在
3. 若文件确实存在,brew 严格意义上还在(只是部分功能可能坏),建议先 brew doctor 排查

Q9. 哪里能反馈 bug? #

• GitHub issue 区
• 飞书工作群

16. 版本历史 #

所有发布版本的更新说明与下载链接。APP 内 系统设置 → 检查更新 按钮会自动对比 hp-version.haoplan.net/haoplan.json 提示新版。每个版本都提供 macOS (Apple Silicon / Intel) 、Windows、Linux (AppImage / deb) 共 5 种安装包。

💡 下载完不能打开? macOS 提示「应用已损坏」请参考 FAQ Q2 的 xattr 命令; Windows 提示「未知发行者」点「更多信息 → 仍要运行」即可。

最新版本 #

历史归档 #

以下版本仅保留更新记录,不再提供下载;如有特殊回退需求请联系工作群。