> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> Topify.ai 平台常见问题——发生了什么、对追踪有什么影响，以及如何解决。

Topify.ai 常见问题的症状、对你数据的影响，以及修复方法。如果你遇到的问题不在这里，请发邮件到 [info@topify.ai](mailto:info@topify.ai)。每个 Guides 页面也都有自己针对该主题的 FAQ 区块。

<Tip>
  联系支持时，附上错误截图和**项目名称**能让我们大幅加快排查速度。
</Tip>

## 新建项目 \[#setting-up-a-new-project]

### 新项目一直停留在"分析中" \[#my-new-project-is-stuck-on-analyzing]

新项目的首次分析是我们最重的一次任务——抓取你的网站、生成搜索词、向多家 AI 服务商询问你的品类。对大型站点来说几分钟是正常的。

**按顺序尝试：**

1. **等 3–5 分钟。** 大多数新项目这都正常。
2. **刷新页面。** 进度条只在加载时从服务器读取，旧页面可能没反映当前进度。
3. **在项目页点击重试。** 如果状态是 `error`，这能解决多数瞬时失败（AI 服务商响应慢、偶发超时）。
4. **在浏览器无痕窗口打开你的网站。** 如果你那边都打不开，我们的分析器也读不到。
5. **联系支持。** 如果卡了超过 15 分钟，请发邮件到 [info@topify.ai](mailto:info@topify.ai)，附上项目名称。

### Topify 无法为我的品牌生成搜索词 \[#topify-could-not-generate-prompts-for-my-brand]

为什么这事重要：搜索词就是 Topify 替你向 AI 助手提的问题。**没有搜索词 = 没东西可追踪。** 如果建议很少甚至为零，常见的原因有：

通常是因为**我们没法从你的网站读到足够的内容来理解你到底做什么**。最常见的几种情况：

* **你的站点屏蔽爬虫。** 很多站点在 `robots.txt`、按 user-agent，或通过 Cloudflare/WAF 规则屏蔽爬虫。如果我们读不了你的网站，就没法据此生成搜索词。（这同样会影响 AI 助手能不能读到你——修了这一点，常常你的 AI 可见度也会变好。）
* **你的首页完全靠 JavaScript 渲染。** 如果 JS 跑起来前页面是空的，基础爬取拿不到任何有用内容。
* **你的站点在登录或付费墙后面。** 任何需要鉴权的内容对我们都是不可见的。
* **品牌名太通用。** 如果品牌名跟常见词撞车，我们无法判断它指什么。
* **网站 URL 错了或重定向到别的地方。** 在项目设置里再核对一次 URL。

**怎么处理：**

* 在 `robots.txt` 和任何 WAF/Cloudflare 规则里允许我们的爬虫。我们用标准 web 客户端的身份来访问。
* 对 JS 重的站点，确保关键页面有有意义的服务端渲染 HTML（标题、描述、产品文案）。
* 在 **Tracking > Prompts > + Add Prompts** 手动添加几个**自定义搜索词**。一旦我们看到几个你真正在意的例子，建议搜索词的效果会好很多。
* 在项目设置里编辑**品牌描述**，给我们更多关于你做什么的上下文。

### 初始化完成但还没收到 AI 回复 \[#setup-finished-but-no-ai-responses-were-collected-yet]

这跟上面情况不同——这里搜索词是有的，但每条搜索词的回复数都是 0。意思是我们已经有追踪计划了，只是还没真正从 AI 服务商那边拿到回复。

**常见原因和修复：**

* **首次运行时所有服务商都超时了。** AI 服务商偶尔会限流或宕机。下一次每日运行会自动重试，或在搜索词上点击 **Retry** 重新拉取。
* **搜索词被过滤了。** 部分服务商会拒绝某些查询（医疗建议、法律建议、成人内容）。改写得更中性一些。
* **你还没启用任何搜索词。** "建议"状态的搜索词不会被追踪。切到 **Active** 标签页，确认至少有一条在那里。

## 内容生成 \[#content-generation]

### 文章生成失败 \[#article-generation-failed]

含义：写作流水线（research → outline → draft → SEO）中的某一步没完成，所以没产出文章。好消息是**生成失败不消耗 credit**——你可以无成本重试。

**逐步诊断：**

| 症状                              | 可能原因              | 修复                                    |
| ------------------------------- | ----------------- | ------------------------------------- |
| 立刻失败                            | 输入无效（搜索词为空、URL 错） | 检查搜索词是否在 1–1,000 字符内；在浏览器里打开参考 URL 验证 |
| 在 **Research** 阶段失败             | 网络搜索服务商挂了，或者主题太冷门 | 等几分钟重试。多加几个关键词，给研究器更多信号               |
| 在 **Reference extraction** 阶段失败 | 某个参考 URL 不可达或屏蔽爬虫 | 移除失败的 URL 或换一个能用的                     |
| 在 **File processing** 阶段失败      | 上传的文件损坏或格式不支持     | 重新导出为 PDF、DOCX、CSV、XLSX 或 TXT 再上传     |
| 在 **Drafting** 阶段失败             | AI 模型暂时过载         | 重试——多数 drafting 失败是瞬时的                |
| 在 **SEO optimization** 阶段失败     | 同 drafting        | 重试                                    |

要重试，打开失败的任务点 **Regenerate**，或用相同输入新建任务。

### 文章生成出来但质量很差 \[#article-was-generated-but-quality-is-poor]

质量问题几乎都源于"输入太单薄"，而不是模型本身。brief 越丰富，文章越好。

**可以补充的内容：**

* **一个具体角度。** "写一篇关于 CRM 的文章"产出的是泛文。"对比 HubSpot 和 Pipedrive，针对早期 SaaS 创业公司，重点放在联系人扩充上"产出的才是真正会被买家读的内容。
* **真实的参考 URL。** 我们会把这些拉进写作器的上下文，让文章可以引用——而引用正是让 AI 助手更愿意复用你内容的关键之一。
* **最多 10 个关键词。** 这是 SEO 步骤会优化的对象，留空会削弱 metadata。

更多请见 [Tutorial: Generate articles](/tutorials/generate-articles#tips-for-higher-quality-articles)。

## 仪表盘和指标 \[#dashboard-and-metrics]

### 初始化完成后仪表盘没有数据 \[#dashboard-shows-no-data-after-setup-finished]

别慌——通常是筛选问题，不是缺数据。

1. **检查日期范围。** 默认是**最近 7 天**。今天创建的项目只有今天的数据——确保今天在所选范围内。
2. **清除服务商和主题筛选。** 筛到某个还没数据的服务商或主题，会把所有内容隐藏掉。
3. **确认初始化真的完成了。** 看一眼项目状态。如果还在 `processing`，指标会在它跑完时填上来。
4. **等首次每日运行。** 初始化会收集一批起步数据。完整的每日采集 24 小时跑一次，所以深夜 bootstrap 的项目第二天才会变厚实。

### Visibility、sentiment 或 position 显示为 0 \[#visibility-sentiment-or-position-is-showing-as-0]

这里的 `0` 意思是**没数据**，不是"你的品牌表现差"。具体来说：

* **Visibility 0%** —— 这段时间里你的品牌没在任何回复中被提到。要么数据还不够多，要么你追踪的搜索词根本没勾起对你品牌的提及。
* **Sentiment 0** —— 你的品牌没被提到，所以没东西可打分。（Sentiment 范围 0–100；真正的"负面"分数落在 30–50 区间。）
* **Position 0** —— 同样：没有提及就没有位置可衡量。

如果你看到全盘是零，先把日期范围拉宽，再看你的搜索词是不是买家在你品类里真正会问的问题。有时候要改的是搜索词，不是品牌。

### 数据日复一日没动 \[#my-numbers-arent-moving-day-over-day]

确认几件事：

* 初始化已经**完成**（不在 `processing` 状态）。
* 至少有一条搜索词在 **Active** 标签页。Suggested 和 inactive 的搜索词都不采集。
* 日期范围包含今天。
* 部分指标（竞争对手排名、来源聚合）要等每日采集周期跑完才重算——清晨太早查时，今天的数字可能还没进来。

## 团队与权限 \[#team-and-access]

### 团队邀请邮件没收到 \[#team-invite-email-never-arrived]

1. **检查垃圾箱/广告邮件**——大多数找不到的邀请都在那里。
2. 在成员页面核对邮箱是否填对。
3. 邀请验证码 **10 分钟**后过期。如果时间过了，重新发送一次。
4. 如果对方已经用同样的邮箱有 Topify 账号，会自动加入——不需要邀请码，直接登录即可。

### "用量超出限额" \[#usage-limit-exceeded]

你撞到了套餐的某项限额。在 **Management > Subscription** 查看当前用量。限额定义和 credit 累积规则见 [账单与套餐](/platform/billing-and-plans)。

### 无法添加更多竞争对手 \[#cannot-add-more-competitors]

撞到套餐的竞争对手上限。要么在 **Preferences > Competitors** 移除不再需要的，要么升级套餐。详见 [账单与套餐](/platform/billing-and-plans)。

## 集成 \[#integrations]

### Search Console 没有显示数据 \[#search-console-not-showing-data]

* 确认 OAuth 时授权的是**正确的 Google 账号**——也就是拥有该资源的那个。
* 我们只能看到该账号至少拥有 Read 权限的资源。
* 首次同步后，数据可能要几分钟才出现。

### CMS 发布失败 \[#cms-publish-failed]

* **WordPress / Shopify / Framer**：在 **Platform > Integrations** 确认 API key 或 OAuth 连接还有效。token 可能过期或被吊销。
* 确认发布用户在目标站点上有创建文章的权限。
* 对 WordPress，检查 REST API 是否启用、是否被安全插件拦截。

## 还需要帮助？ \[#still-need-help]

发邮件到 [info@topify.ai](mailto:info@topify.ai)，告诉我们：

* 你的**项目名称**和问题发生的大致**时间**
* 任何错误信息的**截图**
* 你当时想做什么、期待看到什么结果

我们通常会在一个工作日内回复。