内容
<p align="center">
<img src="Website/public/assets/appclimb-icon.png" width="96" alt="AppClimb 应用图标">
</p>
<h1 align="center">AppClimb</h1>
<p align="center"><strong>在应用商店中了解下一个需要修复的内容。</strong></p>
<p align="center">
AppClimb 将实时排名、竞争对手、评论、元数据和收入信号转化为独立开发者和小型应用团队的专注增长工作区。
</p>
<p align="center">
<a href="https://github.com/skverall/AppClimb/releases/latest/download/AppClimb-macOS.dmg"><strong>下载 AppClimb v0.3.5</strong></a>
· <a href="https://appclimb.app">官方网站</a>
· <a href="#ai-ready-workflows">AI 工作流程</a>
</p>
<p align="center">
<a href="https://github.com/skverall/AppClimb/releases/latest"><img alt="最新版本" src="https://img.shields.io/github/v/release/skverall/AppClimb?style=flat-square&color=6c3df4"></a>
<img alt="macOS 14 或更高版本" src="https://img.shields.io/badge/macOS-14%2B-15142b?style=flat-square&logo=apple">
<img alt="通用 Apple Silicon 和 Intel" src="https://img.shields.io/badge/Mac-Apple%20Silicon%20%2B%20Intel-6c3df4?style=flat-square">
<img alt="Swift 5.9" src="https://img.shields.io/badge/Swift-5.9-f05138?style=flat-square&logo=swift&logoColor=white">
<img alt="MCP stdio" src="https://img.shields.io/badge/MCP-stdio-35a76e?style=flat-square">
</p>
<p align="center">
<img src="docs/assets/appclimb-overview-v0.3.2.png" alt="AppClimb 概览，显示应用商店排名、下一个行动、商业脉搏和增长历史" width="1200">
</p>
<p align="center"><sub>适用于 Apple Silicon 和 Intel Mac 的单个签名和公证的通用下载。</sub></p>
## 您的应用商店增长循环，尽在一处
大多数 ASO 工具为您提供更多图表。AppClimb 连接信号并告诉您现在需要注意什么：关键词差距、排名下降、弱商店页面或下一个值得运行的元数据实验。
- **查看整个攀升过程。** 排名、评论、收入和网站转换率都放在一起，而不是生活在单独的仪表板中。
- **从信号到行动。** ASO 命令中心将实际变化转化为简短的优先行动清单。
- **保持对您数据的控制。** 完整的本地工具包免费使用；可选的 Pro 主机添加同步、服务器监控和警报，同时您的 Mac 关闭。
- **引入您的 AI 代理。** 包含的 CLI 和 MCP 服务器让 Codex、Claude Code 和其他兼容工具在不刮擦 UI 的情况下读取相同的工作区。
## AppClimb 的功能
- **实时应用商店排名和历史图表**
拉取跟踪关键词的实时 iTunes Search API 结果，最高可达公共排名前 200 名，以 SwiftUI Swift Charts 呈现的漂亮交互式图表。
- **Apple Search Ads 活动集成**
跟踪搜索活动、目标关键词出价、展示次数、转化率和消费指标。支持使用证书密钥上传的安全 JWT 身份验证。
- **CoreGraphics PDF 和 CSV 报告**
将关键词排名和活动摘要导出为漂亮的格式化 PDF 报告或原始 CSV 日志，供利益相关者审查。
- **网页分析（类似 DataFast）**
跟踪您的着陆页面，无需 cookie：访客、流量渠道（搜索、社交、AI 助手、电子邮件、付费）、热门页面、设备、浏览器、实时访客、自定义目标和自动网站→应用商店点击跟踪。只需一个脚本标签即可安装 - 请参阅 [docs/web-analytics.md](docs/web-analytics.md)。
- **ASO 命令中心**
将实时排名差距、建议、竞争对手压力和区域健康状况转化为下一个最佳行动卡。
- **本地化元数据工作室**
为每个商店和语言草拟应用名称、副标题、关键词、促销文本和描述。切换语言、跟踪字符限制、预览关键词芯片，并直接将字段复制到应用商店连接中。
- **竞争对手发现**
查看哪些应用出现在您跟踪的搜索中，它们在哪里超越您，以及哪些空白需要元数据空间。
- **客户评论和评分健康状况**
阅读每个商店的最新应用商店评论，按星级过滤，并关注整个列表的评分 - 关键评论被突出显示。
- **后台监控和警报**
当 AppClimb 运行跟踪的应用和区域时，会按照计划重新检查。重要的排名变动、进入/退出前 200 名和新的 1-2 星评论会作为 macOS 通知到达，并在菜单栏面板中收集，类似于实时网站访客。
- **一个屏幕上的商业脉搏**
应用概览显示评分、RevenueCat 收入、网站访客、转化率和网站→应用商店点击率，排名靠前，因此整个漏斗可见。
- **实验时间线**
使用基线排名指标、受影响的元数据字段、目标关键词、评论日期和状态跟踪启动 ASO 实验。
- **AI 就绪访问**
`appclimbctl` 和 `appclimb-mcp` 将您的本地工作区暴露给 AI 编码代理，而不刮擦 UI。
- **首次运行设置和演示工作区**
新用户可以连接自己的 AI 提供商，选择商店、添加真实的应用商店列表，或在触摸实时数据之前打开完整的演示工作区。
## 下载 AppClimb
### 推荐：通用 Mac 应用
下载最新的签名通用构建版本。相同的安装程序在 Apple Silicon 和 Intel Mac 上原生运行：
[**下载 AppClimb v0.3.5 (.dmg)**](https://github.com/skverall/AppClimb/releases/latest/download/AppClimb-macOS.dmg)
· [ZIP 替代方案](https://github.com/skverall/AppClimb/releases/latest/download/AppClimb-macOS.zip)
· [发行说明](https://github.com/skverall/AppClimb/releases/latest)
打开 `AppClimb.app`，然后按照 **首次启动设置** 选择您的 AI 提供商、保存 API 密钥到 Keychain 并添加您的第一个应用。发布的下载版本已使用开发者 ID 签名，并由 Apple 验证，因此它们可以正常打开，无需右键绕过。
### 从源代码构建和运行
```bash
git clone https://github.com/skverall/AppClimb.git
cd AppClimb
./script/build_and_run.sh
```
应用将工作区存储在：
```text
~/Library/Application Support/AppClimb/workspace.json
```
### 安装 CLI 和 MCP 工具
```bash
PREFIX=/usr/local ./script/install_tools.sh
```
如果 `/usr/local/bin` 需要管理员权限：
```bash
sudo PREFIX=/usr/local ./script/install_tools.sh
```
脚本安装：
```text
/usr/local/bin/appclimbctl
/usr/local/bin/appclimb-mcp
```
## CLI 示例
列出跟踪的应用：
```bash
appclimbctl apps
```
获取 ASO 行动计划：
```bash
appclimbctl aso-plan --app Vaqt --region US
```
检查 Mac 和 iPhone 上显示的相同确定性操作：
```bash
appclimbctl actions --app Vaqt --region US
appclimbctl action-status --write --id ACTION_ID --status snoozed
```
阅读版本化的生态系统演示，无需触摸生产数据：
```bash
appclimbctl demo
```
阅读俄语元数据草稿：
```bash
appclimbctl metadata --app Vaqt --region US --lang ru
```
更新一个本地化字段：
```bash
appclimbctl set-metadata --write \
--app Vaqt \
--region US \
--lang ru \
--field description \
--value "本地化的应用商店描述..."
```
导出可复制的应用商店连接元数据：
```bash
appclimbctl export-metadata --app Vaqt --region US --lang ru
```
使用另一个工作区文件：
```bash
APPCLIMB_WORKSPACE_PATH=/path/to/workspace.json appclimbctl apps
```
## AI 就绪工作流程
### 用于 Codex 和 Claude 的 MCP
AppClimb 包含一个_stdio MCP 服务器：
```bash
appclimb-mcp
```
### Codex
```bash
codex mcp add appclimb -- /usr/local/bin/appclimb-mcp
```
### Claude 桌面版
将以下内容添加到您的 Claude 桌面版 MCP 配置文件中：
```json
{
"mcpServers": {
"appclimb": {
"command": "/usr/local/bin/appclimb-mcp"
}
}
}
```
### MCP 工具
服务器公开：
- `list_apps`
- `get_aso_plan`
- `get_keywords`
- `get_competitors`
- `get_metadata_draft`
- `update_metadata_draft`
- `export_metadata`
- `list_experiments`
- `start_experiment`
AI 代理的示例提示：
```text
使用 AppClimb MCP。读取 Vaqt 在美国的 ASO 计划、俄语元数据草稿，然后提出更好的俄语副标题和描述。在我批准之前不要更新任何内容。
```
## 自带 AI 密钥
关键词建议和每周摘要与 OpenAI 兼容的 `/chat/completions` 提供商配合使用。打开 macOS 应用，前往 **设置 -> AI 模型**，选择提供商，粘贴您自己的 API 密钥，保存到 Keychain，然后按 **测试**。
包含的预设：
- DeepSeek：`https://api.deepseek.com` / `deepseek-v4-flash`
- OpenRouter：`https://openrouter.ai/api/v1` / `~openai/gpt-latest`
- OpenAI：`https://api.openai.com/v1` / `gpt-5.5`
- Z.AI / GLM：`https://api.z.ai/api/paas/v4` / `glm-5.2`
- xAI Grok：`https://api.x.ai/v1`
- Together AI：`https://api.together.xyz/v1` / `MiniMaxAI/MiniMax-M3`
- 自定义：任何 OpenAI 兼容的 base URL 和模型名称
API 密钥存储在 macOS Keychain 中，不存储在工作区 JSON 或 Git 仓库中。如果您更喜欢环境变量，AppClimb 会检查：
```text
APPCLIMB_AI_API_KEY
DEEPSEEK_API_KEY
OPENROUTER_API_KEY
OPENAI_API_KEY
ZAI_API_KEY
XAI_API_KEY
TOGETHER_API_KEY
```
CLI 和 MCP 功能不要求 AI 密钥，除非未来的工具明确运行 AI 支持的操作。
## 云账户和集成
应用包含一个本地账户窗口，通过 Hostinger 上的自托管 AppClimb API 使用 Google OAuth。Supabase 和 Appwrite Cloud 不是运行时依赖。API 使用授权码 + PKCE，存储哈希刷新令牌，并将每个账户的数据存储在私有 PostgreSQL 数据库中。参见 [`docs/cloud-accounts.md`](docs/cloud-accounts.md) 以获取公共合约和 [`Backend/README.md`](Backend/README.md) 以获取操作说明。
Keychain 支持的集成中心支持应用商店连接、RevenueCat 和 Apple Search Ads 凭证本地存储。生产配置和安全规则记录在 [`docs/cloud-accounts.md`](docs/cloud-accounts.md) 中。
应用商店连接凭证首先从 Keychain 加载。对于开发和发布自动化，AppClimb 还支持 `~/Library/Application Support/AppClimb/asc-credentials.json` 作为回落；保持用户权限（`chmod 600`）并优先使用 `privateKeyPath` 而不是嵌入私钥。 notarized 版本可以使用 `./script/release.sh` 生成；参见 [`docs/releasing.md`](docs/releasing.md)。
### 云同步（macOS）
登录您的 AppClimb 账户（账户窗口 → 使用 Google 继续），打开 **云同步** 部分。在首次连接时，选择：
- **上传本地到云** - 将您当前的本地工作区推送到云（创建云副本，修订版 0）。
- **从云下载** - 用云副本替换您的本地工作区。
在设置完成后，应用会自动同步本地更改，并带有短暂的延迟，并且始终可用 **立即同步** 按钮。同步使用乐观并发通过 `expected_revision`；如果另一个设备保存了更新的修订版，则应用会显示冲突，并要求您选择 *保留本地* 或 *保留云* - 它永远不会静默覆盖。集成凭证和 AI API 密钥存储在 Keychain 中，从不包含在同步到云的工作区 JSON 中。
## 云同步合约
AppClimb 云同步围绕四个不变式设计：
1. **身份。** 每个工作区文档都带有 `workspaceID` 和 `ownerAccountID`。后端存储服务器端 `workspace_id`，该 `workspace_id` 在首次上传后不可更改。如果客户端的 ID 与服务器的 ID 发生分歧，同步停止并显示“需要初始决定”状态，而不是冒着跨账户数据泄露的风险。
2. **持久化基础。** 每个账户都有一个本地 `sync-metadata.json` 记录客户端已确认的最新云修订版和文档哈希。缺少此文件意味着本地和云历史记录尚未协调，**不会发出自动上传**，直到用户明确选择上传或下载。
3. **无静默覆盖。** 当云移动到本地也有变化时，同步会显示冲突。选择一侧首先会下载被替换一侧的备份，并在服务器端归档 `workspace_revisions`。
4. **归档后再覆盖。** 每次成功的云 PUT，包括 `keep_local`、`keep_cloud` 和 `restore`，都会将先前的文档归档到 `workspace_revisions`，并带有时间戳、源设备 ID 和操作标签。修订版可通过 `GET /v1/workspace/revisions` 和 `POST /v1/workspace/revisions/{id}/restore` 恢复。
本地工作区文件按账户范围存储在 `~/Library/Application Support/AppClimb/Accounts/<accountID>/` 下。退出登录永远不会删除它们；以不同账户登录会加载该账户的专有文件。
## 开发
构建所有内容：
```bash
swift build
```
运行应用包：
```bash
./script/build_and_run.sh
```
验证应用启动：
```bash
./script/build_and_run.sh --verify
```
使用 [`VERSION`](VERSION) 中记录的规范版本号打包本地发布：
```bash
./script/package_release.sh
```
### 网站
```bash
cd Website
npm install
npm run dev
```
创建生产构建版本：
```bash
npm run build
```
早期访问表单发布到 AppClimb 后端的 `POST /v1/waitlist` 端点。API 基 URL 通过 `VITE_API_URL` 环境变量配置（参见 `Website/.env.example`）。对于本地开发对抗正在运行的 Go 后端：
```bash
cp Website/.env.example Website/.env.local # 默认为 http://localhost:8080
cd Website && npm run dev
```
对于生产，请在构建前将 `VITE_API_URL` 设置为部署的 API URL。**注意：** 等待列表端点仅在后端部署和迁移后接受真实注册 - 参见 [Backend/README.md](Backend/README.md)。直到那时，表单会在提交时显示错误。
### iPhone 应用
iOS 配套应用位于 `iOS/AppClimbMobile`。它是您云 ASO 工作区的 **只读** 视图：使用 Google 登录，查看跟踪的应用、关键词排名和实验，具有离线缓存和下拉刷新。
```bash
cd iOS/AppClimbMobile
xcodegen generate
open AppClimbMobile.xcodeproj
```
从命令行构建和运行测试（外部卷上的 DerivedData）：
```bash
cd iOS/AppClimbMobile
xcodebuild -project AppClimbMobile.xcodeproj -scheme AppClimbMobile \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
-derivedDataPath /Volumes/LexarDev/Developer/Temp/AppClimbDerivedData build
```
应用包括今日仪表盘、关键词移动、实验跟踪、设置、AppClimb 徽标和生产图标。清晰标记的 **演示模式** 加载示例数据而无需登录。编辑元数据和启动实验不可在 iPhone 上使用此测试版 - 这些操作显示诚实的“继续在 Mac 上继续”提示。
发布工件写入：
```text
dist/release/
```
通过发布工作流发布签名、公证的通用 GitHub 版本：
```bash
gh workflow run notarized-release.yml -f version="$(< VERSION)"
```
工作流创建版本标签和 GitHub 版本，然后上传公证的 `.dmg`、应用 `.zip`、稳定最新下载资产和 CLI/MCP 工具。
构建发布工具：
```bash
swift build -c release --product appclimbctl
swift build -c release --product appclimb-mcp
```
## 数据安全
AppClimb 默认情况下保留所有工作区数据本地。当您启用云同步（请参见上文），工作区 JSON 同步到您的私有 AppClimb 云工作区；账户会话、AI API 密钥和集成凭证始终存储在 Keychain 中，从不包含在同步文档中。MCP 服务器和 CLI 读取相同的本地 JSON 文件。它们不会自行上传您的数据。
安全测试，请复制副本并指向工具：
```bash
cp "$HOME/Library/Application Support/AppClimb/workspace.json" /tmp/workspace.json
APPCLIMB_WORKSPACE_PATH=/tmp/workspace.json appclimbctl set-metadata --write ...
```
## 已知限制（第一个测试版）
- **iOS 故意仅支持低风险编辑。** 它可以进行三重操作、移动实验审查日期、添加观察笔记、记录审查决定，并快速通过受保护的 API API 查看关键词。
- **云同步是可选的。** 本地操作仍然是默认设置；同步仅在您登录并选择初始上传或下载后激活。
- **自动同步延迟。** 快速编辑会在短暂延迟后批量处理为一次上传；冲突被显示，而不是静默覆盖。
## 需求
- macOS 14+
- Swift 5.9+
- 通过 Apple 公共 iTunes Search API 访问应用商店数据
- 可选：用于关键词建议和每周摘要的 AI API 密钥
