内容
# ASO 副驾驶
一个自我托管的、免费的替代工具，如 rankd.dev/AppTweak/ASOMobile，用于开发者管理自己的应用。单用户，无需账号，无需计费 —— 只有你的应用。
还暴露了一个 MCP 服务器，以便代理（Claude Code、Claude Desktop 等）可以直接管理你的 ASO：添加应用、跟踪关键词、拉取健康报告、监视竞争对手、查找关键词机会，并自己编写 AI 复制建议，无需单独的 API 密钥。
https://github.com/user-attachments/assets/970ce32e-a980-42ce-a0eb-529c425439af
## 功能
- **每日关键词排名跟踪** — 来自实时应用商店/谷歌应用商店搜索结果的真实排名
- **无限应用、关键词、竞争对手** — 这是你的数据库，没有计划限制
- **竞争对手间谍** — 跟踪竞争对手应用，并查看他们在你跟踪的每个关键词的排名
- **健康评分分析** — 标题/副标题/截图/描述/评分/新鲜度分析，并提供建议，与付费工具相同
- **关键词研究** — “查找获胜关键词”从你的和竞争对手的元数据中派生候选词，并使用实时商店搜索数据评估其需求/难度
- **全球覆盖** — 在约 40 个主要应用商店/谷歌应用商店中扫描关键词的排名，并在世界地图上显示
- **评论分析** — 评分分布，积极/消极主题提取，以及关键词差距查找器，从你自己的评论中挖掘未跟踪的搜索词
- **产品健康叠加层** — 将应用的真实每日活跃用户（通过每个应用的 PostHog 项目）与其 ASO 健康评分在同一窗口期内配对
- **AI 复制建议** — 重写标题/副标题/描述，适用于 8 种语言（美国/英国/加拿大英语、西班牙语、德语、法语、葡萄牙语、日语），将关键词适应为真实的本地搜索词，而不是直接翻译。有两种生成方式，无需锁定：
- 通过 [OpenRouter](https://openrouter.ai)（任何支持的模型）通过 Web UI，或
- **无需密钥**，通过将任何 MCP 连接的模型（例如 Claude Code）指向 `prepare_copy_localization_brief` / `save_copy_suggestions` 工具 —— 模型自行编写复制，无需超出您已为代理支付的 API 费用
- **MCP 服务器**，位于 `/api/mcp`，用于代理驱动的 ASO 管理
## 技术栈
Next.js（应用路由器）+ Prisma + PostgreSQL。商店数据来自公共的 iTunes 搜索/查找 API（应用商店）和 `google-play-scraper`（谷歌应用商店）。没有用于搜索量或关键词排名位置的免费官方 API，因此：
- **排名位置** 是真实的：它是你的应用在该术语的实时搜索中的实际索引。
- **搜索量/难度** 是启发式的（0-100），源自结果计数和竞争对手权威代理，而不是真实的搜索量 —— 没有免费的来源。
- iOS **副标题** 从公共的应用商店产品页面抓取（未由 iTunes API 暴露）。如果苹果更改了页面标记，这可能会默默地开始返回 `null` —— 请参见 `src/lib/stores/appstore.ts` 中的 `fetchSubtitle`。
- 每个商店调用（两个平台）都会重试暂时性故障（429、5xx、网络错误），并通过 `src/lib/withRetry.ts` 进行退避，因此一个速率限制的请求不会使整个每日跟踪过程失败。
## 设置
```bash
npm install
docker compose up -d # 本地 Postgres，端口 5433
npx prisma migrate dev # 创建表
npm run dev
```
打开 http://localhost:3000，点击 **添加应用**，搜索你的应用并添加它。
复制 `.env.example` 到 `.env` 并调整 `DATABASE_URL`，如果你指向不同的 Postgres 实例（例如 Supabase/Neon/RDS 而不是捆绑的 docker-compose）。
## 每日跟踪
排名检查不会自动运行 —— 每天触发一次 `POST /api/track`（由 `.env` 中的 `CRON_SECRET` 保护）：
```bash
curl -X POST http://localhost:3000/api/track -H "Authorization: Bearer $CRON_SECRET"
```
`scripts/daily-track.sh` 为 cron 包装了这一点：
```cron
0 6 * * * APP_URL=http://localhost:3000 CRON_SECRET=... /path/to/scripts/daily-track.sh >> /var/log/aso-track.log 2>&1
```
任何外部调度器都可以使用相同的方式（GitHub Actions `schedule:` 触发器、托管提供商的 cron 作业等）—— 它只需要每天访问一个端点。
### 或运行捆绑的 cron 容器
`docker compose up -d cron` 启动一个小的 Alpine 容器（`docker/cron/`），通过 `crond` 按计划运行 `scripts/daily-track.sh`，通过 `host.docker.internal` 访问应用，因为应用本身在主机上运行，而不在 Docker 中。通过 `.env` 配置：
```bash
CRON_SECRET="..." # 必需，与应用自己的 .env 共享
APP_URL="http://host.docker.internal:3000" # 可选，这是默认值
CRON_SCHEDULE="0 6 * * *" # 可选，标准 5 字段 cron 语法
```
## 连接代理（MCP）
应用在 `/api/mcp` （可流式传输的 HTTP 传输）处暴露了一个 MCP 服务器，带有用于列出应用、搜索商店、添加应用/关键词/竞争对手、拉取健康报告、查找获胜关键词、生成 AI 复制建议和按需运行跟踪通过的工具。
将任何兼容 MCP 的客户端指向它，例如在 Claude Code（`.mcp.json`，已在存储库根目录中检查，指向 localhost）：
```json
{
"mcpServers": {
"aso-copilot": {
"url": "http://localhost:3000/api/mcp"
}
}
}
```
默认情况下，此端点没有身份验证 —— 它对你的 ASO 数据具有完全的读写访问权限。在将其暴露到 localhost 以外之前，在 `.env` 中设置 `MCP_AUTH_TOKEN`，然后让你的客户端发送它：
```json
{
"mcpServers": {
"aso-copilot": {
"url": "http://localhost:3000/api/mcp",
"headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
}
}
}
```
## AI 复制建议
在每个应用的“概览”选项卡上的 `src/components/AICopySuggestions.tsx` 中，有两种独立的方式来生成重写的标题/副标题/描述复制内容 - 选择其中一种，两者都写入同一个 `AiCopySuggestion` 表中，因此面板显示最近运行的哪一个：
- **OpenRouter** （适用于 Web UI）：在 `.env` 中设置 `OPENROUTER_API_KEY`（在 [openrouter.ai/keys](https://openrouter.ai/keys) 获取）；可选地设置 `OPENROUTER_MODEL` 以选择与默认模型不同的模型。点击 **获取 AI 建议**。
- **MCP，无需密钥**：让连接的 MCP 模型调用 `prepare_copy_localization_brief`（返回当前复制内容、字符限制和每个本地化的说明 - 无需网络调用，无需密钥），然后编写复制内容本身，然后使用 `save_copy_suggestions` 持久化它。对于已经为代理付费并且不想为此支付第二个 LLM 账单的人来说非常有用。
## 分析（可选）
两个独立的 PostHog 集成 - 不要混淆：
<img width="1558" height="521" alt="image" src="https://github.com/user-attachments/assets/04985484-c04c-4e2d-95c4-65c56c2f9e1c" />
- **此工具的自身使用分析**（您是否正在此应用中点击浏览，而不是任何跟踪应用的用户）—— 默认关闭。在 `.env` 中设置 `NEXT_PUBLIC_POSTHOG_KEY`（和可选的 `NEXT_PUBLIC_POSTHOG_HOST`，如果自行托管 PostHog）以启用通过 `src/components/PostHogProvider.tsx` 的页面视图跟踪 - 无需代码更改，它在密钥设置之前是无操作的。
- **每个应用的产品健康状况** - 每个跟踪的应用都可以链接其**自己的** PostHog 项目（“设置”选项卡，`src/components/PostHogSettings.tsx`），以便其真实的每日活跃用户显示在“概览”选项卡中，与其 ASO 健康评分并列。 与上面的密钥无关； 在 UI 中按应用配置，不通过环境变量配置。
## 项目布局
- `src/lib/stores/` — 应用商店（iTunes）和谷歌应用商店的数据获取
- `src/lib/health.ts` — 健康评分引擎
- `src/lib/research.ts` — 关键词候选生成 + 搜索量/难度评分
- `src/lib/ai.ts` / `src/lib/aiLocales.ts` — AI 复制建议：OpenRouter 提示、密钥免费的本地化简介生成器和 8 种语言列表
- `src/lib/reviewAnalysis.ts` — 评分分布 + 积极/消极主题提取
- `src/lib/posthogIntegration.ts` — 每个应用的 PostHog 客户端（每日活跃用户查询）
- `src/lib/storeLinks.ts` / `src/lib/metricColor.ts` — 小型共享 UI 帮助程序（外部商店链接，搜索量/难度着色）保留在 `research.ts` 之外，以便导入它们的客户端组件不会拖入仅限服务器的商店抓取依赖项
- `src/lib/appService.ts` — REST API 和 MCP 工具共用的逻辑
- `src/app/api/` — REST 路由
- `src/app/api/[transport]/route.ts` — MCP 服务器
- `docker/cron/` — 用于每日跟踪的可选捆绑 cron 容器（参见上面的“每日跟踪”）
