docs(user-manual): add product user manual aligned to live code

Cover onboarding, workspace, article creation, brand library, media
publishing, knowledge base, image library, GEO tracking, desktop client,
KOL marketplace, AI points, and FAQ — sourced from actual views and i18n
rather than the v1 PRD.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

user-manual/01-入门指南.md

@@ -0,0 +1,94 @@
+# 入门指南
+
+本章帮你在第一次登录后用最短路径走完一遍完整链路：从账号准备到文章成功发布到媒体平台。
+
+## 1. 登录
+
+访问运营/管理员提供的省心推 Web 控制台地址，进入登录页：
+
+- 标题：**租户后台登录**
+- 输入项：**手机号 / 邮箱** 与 **密码**
+- 可勾选 **记住密码**；若忘记密码，请联系本租户的管理员重置（自助找回入口当前为占位）
+
+登录成功后默认跳转到 **工作台**。左侧导航分为：工作台 / 文章创作 / 品牌管理 / 数据追踪 / 内容管理 / 精调模板市场 / 个人中心；如果你已被授权为 KOL，会额外出现 **KOL 工作区**。
+
+## 2. 起步五步走
+
+> 顺序很关键。跳步通常会导致后续生成或发布失败。
+
+### 步骤 1 · 在「品牌词库」建好品牌
+
+进入左侧 **品牌管理 → 品牌词库**，点击 **新建品牌**：
+
+- **品牌名称**：必填
+- **公司官网**：选填，但**强烈建议填**。AI 在文章生成时会基于官网抓取上下文
+- **品牌描述**：建议简要写一两句业务定位
+
+> ⚠️ **如果没有公司官网，必须先去知识库建立公司资料**：进入 **内容管理 → 知识库**，添加文档、网站链接或纯文本，把"公司是谁、做什么、卖什么、面向谁"讲清楚。否则后续 AI 分析会拿不到品牌上下文，生成质量会明显下降。
+
+### 步骤 2 · 在选定品牌下添加关键词
+
+品牌创建成功后，左侧"品牌库"会自动选中刚建好的品牌。切到 **关键词** Tab：
+
+- 点击 **新建关键词**，每个关键词代表一个你希望被 AI 搜索引擎覆盖的主题
+- 关键词总量受套餐配额限制（页面顶部会显示 **总关键词已用 X / Y**）
+- 单品牌已绑定关键词数也会单独展示
+
+### 步骤 3 · 给每个关键词加 1~2 个核心问题
+
+在关键词列表里点击任一关键词，右侧问题集会切换为该关键词下的问题列表，点击 **新建问题**：
+
+- **每个关键词建议先维护 1~2 个核心问题**，覆盖最高频的用户提问
+- 问题集是后续 **数据追踪** 用来采样 AI 回答的入口；没有问题就没有可追踪的数据
+- 单关键词下的问题数有上限，套餐越高上限越大，达到上限会提示"当前关键词下最多可维护 X 个问题"
+
+### 步骤 4 · 安装桌面客户端并绑定平台
+
+绑定媒体账号、绑定 AI 平台、采集 AI 回答、真实发布到第三方平台，**全部依赖桌面客户端**。
+
+1. 从运营或管理员处获取桌面客户端安装包
+2. 安装并使用**与 Web 端相同的账号**登录桌面客户端
+3. 进入桌面端 **媒体账号** 页面，从平台卡片点击 **去绑定**，在弹出的浏览器窗口完成第三方账号登录；省心推服务端**不会保存第三方平台的 cookie**，登录态由本地客户端持有
+4. 进入桌面端 **AI 平台** 页面，绑定至少一个 AI 对话平台（豆包、文心一言、通义千问、DeepSeek、Kimi、混元/元宝）。这是 **数据追踪** 能拿到引用数据的前提
+
+完整桌面端使用见 [桌面客户端](./09-桌面客户端.md)。
+
+### 步骤 5 · 生成第一篇文章并发布
+
+回到 Web 端：
+
+1. 进入 **工作台**，点击顶部任意一张 **普通通用模版** 卡片（Top X、产品评测、研究报告、品牌词扩写）
+2. 进入模版向导：
+   - **第 1 步 基本信息**：选品牌、确认关键词与竞品、填模版字段（如评测主题、TopX 主题等）
+   - **第 2 步 文章结构**：从 AI 给出的 5 个标题候选中选一个或自定义；调整结构段落
+   - **第 3 步 生成文章**：确认大纲与关键要点，点击 **提交并生成**
+3. 任务进入生成队列，列表会自动刷新；状态从 **生成中** 变为 **已完成**
+4. 在 **最近生成** 列表中点击 **发布**：
+   - 弹窗会列出"当前文章可发布的平台"
+   - 只有"租户已绑定 + 当前桌面客户端在线 + 本地登录态有效"的账号才可勾选
+   - 部分平台（如微信公众号、百家号、懂车帝）要求**封面图**，未上传会被拦截
+   - 提交后桌面客户端会逐个平台执行真实发布，并把外链回写到文章
+
+## 3. 第一次发布之后
+
+完成首篇发布后，再扩展使用以下能力：
+
+| 想做的事 | 去哪里 | 章节 |
+| --- | --- | --- |
+| 用更灵活的 Prompt 生成 / 定时生成 | 文章创作 → 自定义生成 | [03-文章创作](./03-文章创作.md) |
+| 把别人的好文章改写成自己的 | 文章创作 → 仿写创作 | [03-文章创作](./03-文章创作.md) |
+| 不依赖 AI、纯手写一篇 | 文章创作 → 自由创作 | [03-文章创作](./03-文章创作.md) |
+| 上传图片素材并跨文章复用 | 内容管理 → 图片管理 | [07-图片管理](./07-图片管理.md) |
+| 看品牌在 AI 搜索里的引用排名 | 数据追踪 → 数据详情 | [08-数据追踪](./08-数据追踪.md) |
+| 看 AI 点数还剩多少 | 个人中心 → AI 点数明细 | [11-AI点数与套餐](./11-AI点数与套餐.md) |
+| 订阅 KOL 上架的精调模板 | 精调模板市场 | [10-精调模板与KOL](./10-精调模板与KOL.md) |
+
+## 4. 常见起步坑
+
+- **没绑定品牌就直接去模版创作**：模版向导第 1 步会报"请先选择品牌或填写品牌信息"。
+- **品牌只填了名字，官网空、知识库也空**：AI 分析阶段品牌摘要、关键词候选、竞品候选会大量空白。
+- **没装桌面客户端就在 Web 端点发布**：发布弹窗里所有平台都会变灰、Tooltip 提示"本地未登录"或"客户端离线"。
+- **桌面端绑定了媒体账号但没绑定 AI 平台**：能发布，但数据追踪页会一直空着，立即采集按钮也会被禁用。
+- **关键词建了但没加问题**：数据详情的"高频问题"和"引用排行"全部为空。
+
+跑过一遍完整链路后，再翻 [常见问题](./12-常见问题.md) 排查具体故障会更顺手。

user-manual/02-工作台.md

@@ -0,0 +1,66 @@
+# 工作台
+
+工作台（路径 `/workspace`）是登录后默认进入的首页，用一张大图把当前账号的核心状态聚合到一起。它包含四块区域。
+
+## 1. 普通通用模版
+
+页面左上方的横向卡片区。每张卡片对应一类预置文章模版：
+
+- **Top X 文章**：盘点榜单类长文（如「2026 年 X 类目 Top 10」）
+- **产品评测文章**：单产品深度评测，含引言钩子和评测结构
+- **研究报告文章**：偏报告体例，结构更标准化
+- **品牌词扩写**：围绕品牌或关键词扩写覆盖式内容
+- **模板持续扩展中**（占位卡）：当前后端可用模版不足 4 个时显示
+
+点击卡片会跳转到 `/articles/wizard?template_id=...` 进入模版向导。详细向导步骤见 [文章创作 §模版创作](./03-文章创作.md#1-模版创作)。
+
+## 2. 数据总览
+
+右上方的四宫格，展示当前租户的累计指标：
+
+| 指标 | 含义 |
+| --- | --- |
+| **生成数** | 当前账号已生成的文章总数（含失败、草稿） |
+| **发布数** | 已成功发布的文章数（按文章维度） |
+| **品牌数** | 在品牌词库中创建的品牌总数 |
+| **媒体账号数** | 当前租户已绑定且属于发布媒体类别的账号数（不含 AI 平台账号） |
+
+> 注意：媒体账号数走的是"桌面客户端实际登记的账号"，所以你**只在 Web 端绑定但没在桌面客户端走完登录态**的平台不会被计入。
+
+## 3. KOL 精调模版（按需出现）
+
+如果当前租户已订阅过 KOL 上架的精调订阅包，工作台会单独出现一块 **精调模版** 区，按 `更新时间 → 授权时间` 倒序展示。每张卡片包含：
+
+- 提示词名称、所属订阅包名称
+- KOL 显示名（首字母头像）和适用平台标签
+- 封面图（订阅包配置的图）
+
+点击卡片直接进入 `/kol/generate/:subscriptionPromptId`，使用该精调模版生成文章。订阅市场参见 [精调模板与 KOL](./10-精调模板与KOL.md)。
+
+## 4. 最近生成
+
+页面下方的表格，列出当前账号最近的文章。字段：
+
+- **文章标题**：标题 + 来源元信息（模版/自定义/仿写/自由创作 + 创建时间）
+- **生成状态**：草稿 / 队列中 / 生成中 / 已完成 / 生成失败
+- **发布状态**：未发布 / 发布中 / 发布成功 / 部分成功 / 发布失败
+- **字数**：成稿字数；草稿态显示 `--`
+- **操作**：右对齐的按钮组，按状态决定可点项
+
+操作按钮：
+
+| 按钮 | 触发的动作 |
+| --- | --- |
+| **发布** | 仅在文章生成已完成时可用，弹出发布弹窗；调用桌面客户端把文章推送到选中的发布平台 |
+| **编辑** | 模版未提交（草稿）时进入向导继续编辑；其他状态进入独立 `ArticleEditorView` |
+| **预览** | 打开侧边抽屉查看文章正文 |
+| **复制** | 把文章正文（带标题和段落）复制到剪贴板 |
+| **删除** | 二次确认后删除文章记录；不会删除已经发布到第三方平台的内容 |
+
+> 列表存在"生成中/排队中"的文章时，前端会每 10 秒自动轮询刷新一次，直到所有任务结束。手动点击 **刷新** 可立即触发。
+
+## 5. 常见用法
+
+- **快速续写未提交的草稿**：在最近生成里找到状态为 `draft` 的模版任务，点 **编辑**，向导会带着原表单数据回到对应步骤。
+- **查看一篇文章的全部发布记录**：在最近生成里点击文章标题打开侧边抽屉，最下方有「已发布详情」Tab，能看到每个平台的发布时间、状态和外链。
+- **总览跟实际感觉不符**：工作台的指标查询带 `workspace.overview` queryKey，会跨页面缓存；切到 **品牌词库** 或 **媒体管理** 操作完成后，回到工作台会自动刷新。如果还不一致，点击最近生成右上角的 **刷新** 按钮强制拉取。

user-manual/03-文章创作.md

@@ -0,0 +1,134 @@
+# 文章创作
+
+左侧导航 **文章创作** 分为四个独立子模块，定位完全不同：
+
+| 子模块 | 路径 | 适用场景 |
+| --- | --- | --- |
+| **模版创作** | `/articles/templates` | 用预置结构化模版（Top X、产品评测等）批量产稿 |
+| **自定义生成** | `/articles/custom` | 自维护 Prompt 规则，做即时或定时生成；定时任务可挂自动发布 |
+| **自由创作** | `/articles/free-create` | 不依赖 AI，纯手动新建并编辑文章 |
+| **仿写创作** | `/articles/imitations` | 从一篇外部文章 URL 出发，抓取后改写成自己的版本 |
+
+## 1. 模版创作
+
+### 列表页
+
+- 顶部分两个区：**普通通用模版** + **精调模版**（精调模版区只在租户订阅过 KOL 包时出现）
+- 顶部操作：**选择模版创作**（弹窗里挑模版） / **批量生成文章** / **重置筛选**
+- 筛选项：模版类型、生成状态、发布状态、生成时间范围、标题关键字
+- 列表字段：标题、模版类型、生成状态、发布状态、字数、操作
+
+### 模版向导（三步）
+
+进入向导后页面分为三步，每一步都不能跳过：
+
+#### 步骤 1：基本信息
+
+- **文章语言**：中文简体 / English
+- **模版字段**：跟所选模版相关，比如 Top X 主题、评测对象、报告主题
+- **品牌上下文**（强烈建议）：
+  - 从品牌库选品牌后会自动带出 **AI 品牌摘要**、**关键词**、**竞品列表**
+  - 也可手输品牌名+官网，点击 **分析** 让 AI 现场补齐摘要、关键词、竞品和标题候选
+  - 竞品支持手动追加；只有从品牌库选过品牌的会话，才能把新加的竞品 **收藏** 回品牌词库
+
+> AI 分析过程会消耗 AI 点数（计入 `template_analyze`、`template_title_generate` 等条目）。
+
+#### 步骤 2：文章结构
+
+- **选择文章标题**：AI 给出 5 个候选标题，可挑选或自定义改写
+- **评测引言钩子**（仅产品评测模版可见）：选一种开场风格，AI 会按这种语气写引言
+- **文章结构**：AI 给出默认段落结构，可增删段落
+- **预览**：右侧实时按当前标题+结构渲染文章框架
+
+#### 步骤 3：生成文章
+
+- **确认大纲**：AI 在这一步生成完整大纲（章节+小节），可继续编辑节点
+- **关键要点**：补充本次出稿想强调的卖点、观点、风格要求
+- **生成说明**：默认显示"提交后会进入异步生成队列，列表会自动刷新"
+- 点击 **提交并生成** → 后端落一篇文章记录 + 一个生成任务，列表自动跳回
+
+### 模版列表的状态规则
+
+- 只有 **生成已完成** 的文章可以发布
+- 只有 **草稿 / 生成失败 / 已完成** 三种状态可编辑
+- 删除有二次确认，提示"已发布平台的内容不会被删除"
+
+## 2. 自定义生成
+
+`/articles/custom` 用四个 Tab 把流程拆开：
+
+| Tab | 用途 |
+| --- | --- |
+| **生成文章** | 累计的产出列表，按 Prompt 规则、发布状态、生成状态、标题、时间筛选 |
+| **即时任务** | 一次性生成，填表→立即跑 |
+| **定时任务** | 按 Cron 周期自动生成；**支持挂自动发布**（PRD 里明说不支持，但实际代码已开放） |
+| **Prompt 规则** | 自维护 Prompt 模板，可分组、启用/停用 |
+
+### Prompt 规则
+
+字段：规则名称、Prompt 内容（支持变量占位符）、适用场景、默认语气、默认字数（建议 ≤ 6000，主流大模型单次输出存在限制）、状态、关联文章数。规则可分组，支持「未分组」回收站。
+
+### 即时任务
+
+填好 **基础信息**（任务名 / 选择 Prompt / 目标平台 / 品牌）+ **高级设置**（额外参数）→ 点击 **立即生成** → 后端排队执行。任务执行状态、执行时间、创建时间会回写到列表。
+
+### 定时任务
+
+字段拆为四组：
+
+1. **基础信息**：任务名、关联 Prompt 规则、关联品牌、Cron 频率（每天一次 / 每天两次 / 每周一次 / 自定义 Cron）、起止时间、生成篇数
+2. **发布平台**：跟媒体管理同步绑定状态；多选；未绑定/未授权的平台不可选
+3. **发布设置**：
+   - **是否自动发布** 开关：开启后定时生成完的文章会**直接进入发布队列**，由桌面客户端执行
+   - **媒体账号**：必须选具体账号；客户端离线会先排队，上线继续发
+4. **封面图**：默认不设置；选了"要求封面"的平台时，必须先选封面，否则提交会被拦截
+
+### 列表筛选
+
+字段：Prompt、定时任务、发布状态、标题、生成状态、生成时间。
+
+## 3. 自由创作
+
+`/articles/free-create` 是给"不想用 AI、就是要纯手动"的场景。
+
+- 顶部按钮：**新建文章**
+- 列表字段：标题、字数、发布状态、最后修改时间、操作
+- 筛选项：发布状态、生成时间、标题关键字
+- 新建后直接进入独立的 `ArticleEditorView` 富文本编辑器
+
+文章保存后同样会进入文章列表，与模版/自定义/仿写文章共用发布流程。
+
+## 4. 仿写创作
+
+`/articles/imitations` 用于把别人的好文章（合规内容）改写成自己的表达。
+
+### 列表页
+
+字段同其他文章列表，多一个 **原文** 列展示来源。空状态文案：「还未创建仿写文章，可从问题详情的引用来源一键带入，也可以手动新建。」
+
+### 新建仿写
+
+`/articles/imitations/create`，分两段：
+
+#### 来源文章
+
+- **文章 URL**（必填）：后端会先抓取 URL 内容
+- **来源标题**：选填，引用来源标题会自动带入
+
+#### 仿写设置
+
+- **文章语言、行业/场景、品牌/主体、地域、目标读者、内容目标、语气风格、篇幅要求**
+- **关键词**：回车多选
+- **必须保留/强调**：列出必须出现的事实、数据、观点
+- **需要规避**：列出不能出现的说法、竞品、合规禁区
+- **其他要求**：自由文本
+- **允许联网补充**：开启后大模型会参考实时网页信息，适合需要最新事实或行业动态的仿写
+- **引用知识库**：选择后端会从知识库检索相关片段作为参考；不选则只基于源文章和上方设置生成
+
+提交后任务进入排队，状态走"队列中 → 生成中 → 已完成"。常见入口：在 [数据追踪](./08-数据追踪.md) 的引用来源里点 **仿写创作**，可以一键把那篇被引用的外部文章带入此页。
+
+## 跨子模块的通用规则
+
+- **删除文章**：所有列表都会二次确认，已发布到第三方平台的内容**只删本地记录**
+- **AI 点数预占**：AI 相关动作（生成、AI 分析、片段优化等）会先**预占点数**，任务成功后确认扣除；任务失败系统自动退回（详见 [AI 点数](./11-AI点数与套餐.md)）
+- **状态轮询**：所有列表在存在「生成中」任务时会自动轮询刷新，约 10 秒一次

user-manual/04-品牌词库.md

@@ -0,0 +1,95 @@
+# 品牌词库
+
+路径 `/brands`。这是新用户登录后**第一个必须打开**的页面，所有后续模块（文章生成、数据追踪、知识库引用）都依赖这里维护好的品牌资产。
+
+## 1. 页面结构
+
+- 左侧 **品牌库** 面板：当前账号下的全部品牌；选中后右侧才会有数据
+- 右侧分两个 Tab：**关键词** / **竞品库**
+- 顶部信息条：当前套餐 + 当前品牌已绑定关键词数 + 全局关键词配额已用情况
+
+## 2. 品牌
+
+### 新建品牌
+
+字段：
+
+- **品牌名称**（必填）
+- **公司官网（选填）**：强烈建议填。AI 在文章生成时会用官网作为品牌上下文采集源
+- **品牌描述**：建议简要写业务定位
+
+> ⚠️ **没有公司官网的，必须先去[知识库](./06-知识库.md)上传公司资料**（文档、网站链接或纯文本，把公司业务、产品、定位讲清楚）。否则模版向导里的"AI 品牌摘要、关键词候选、竞品候选"会大量空白。
+
+### 编辑 / 删除品牌
+
+- 编辑：右上角"…"菜单 → 编辑品牌
+- 删除：会二次确认；删除品牌会一并清掉它名下的关键词、问题集、竞品
+
+### 套餐限额
+
+页面顶部的"品牌公司"卡片标注了当前套餐的限制：
+
+- 免费版默认 **1 个**
+- 付费版默认 **2 个**
+- 达到上限时新建按钮置灰，并提示「当前套餐最多可绑定 X 个品牌公司」
+
+## 3. 关键词
+
+切到 **关键词** Tab 后：
+
+- 左侧关键词列表，每条显示关键词名称、问题数（动态计数）
+- 顶部 **新建关键词** 按钮
+- 选中关键词后，右侧问题集会切到该关键词下
+
+### 新建关键词
+
+仅一个字段：**关键词名称**。一个关键词代表你希望在 AI 搜索里覆盖的一个主题方向。
+
+### 关键词配额
+
+- 全局有"总关键词数"上限（按账号套餐计）
+- 单品牌内对关键词数没有硬上限，但占用全局额度
+- 顶部进度条「总关键词已用 X / Y」实时反映
+
+## 4. 问题集
+
+每个关键词下挂载一组核心问题。问题集是 [数据追踪](./08-数据追踪.md) 的采样源——没有问题就没有可监控的 AI 回答。
+
+### 新建问题
+
+- 选中关键词后，右侧 **新建问题**
+- **问题内容**：填用户在 AI 搜索里最可能问的问句
+
+### 操作
+
+每个问题支持：
+
+- **查看数据**：跳转到 [数据详情 → 问题详情页](./08-数据追踪.md#3-问题详情页)，看每个 AI 平台对该问题的回答和引用情况
+- **删除**：二次确认后移除
+
+### 单关键词问题数上限
+
+- 套餐越高上限越大
+- 接近上限时页面会提示「问题 X / Y」
+- 达到上限新建按钮置灰，提示「当前关键词下最多可维护 X 个问题」
+
+> 建议：每个关键词先维护 1~2 个核心问题跑通数据采集流程，确认数据详情有效后再补全。
+
+## 5. 竞品库
+
+切到 **竞品库** Tab：
+
+- 列表字段：竞品名称、竞品官网、竞品描述、重点产品线、操作
+- **新建竞品** 字段：竞品名称、竞品官网、竞品描述、重点产品线（用英文逗号分隔多个产品线）
+- 编辑/删除入口在每行操作列
+
+竞品库的用途：
+
+1. **模版向导第 1 步** 会把当前品牌的竞品自动带入"竞品列表"。AI 在生成 Top X、产品评测时会把这些竞品作为对比对象
+2. **模版向导里手动添加的竞品**，可点击"收藏"按钮回写到这里（前提是从品牌库选过当前品牌）
+
+## 6. 常见问题
+
+- **新建按钮一直置灰**：检查页面顶部的配额条；通常是品牌/关键词/问题数已到套餐上限
+- **AI 分析结果总是空**：确认品牌"公司官网"已填写，或在知识库已有该品牌的资料；二者都没有时 AI 拿不到上下文
+- **删除品牌后数据追踪还能看见旧数据**：数据快照不会随删除一起清理，会按窗口期自然过期

user-manual/05-媒体管理与发布.md

@@ -0,0 +1,109 @@
+# 媒体管理与发布
+
+路径 `/media`。这是 Web 端的**只读+查看**页面，用来看当前租户绑定的发布媒体账号、它们的健康度、最近一次校验时间。**真正的"绑定"和"发布"动作都在桌面客户端里执行**。
+
+## 1. 当前支持的发布平台
+
+省心推目前内置 13 个发布媒体平台：
+
+| 平台 | 短名 | 备注 |
+| --- | --- | --- |
+| 头条号 | 头 | UGC 媒体 |
+| 百家号 | 百 | UGC 媒体，要求封面图 |
+| 搜狐号 | 搜 | UGC 媒体 |
+| 企鹅号 | Q | UGC 媒体 |
+| 知乎 | 知 | UGC 媒体 |
+| 网易号 | 网 | UGC 媒体 |
+| 简书 | 简 | UGC 媒体 |
+| bilibili | B | UGC 视频/专栏 |
+| 稀土掘金 | 掘 | 技术社区 |
+| 什么值得买 | 值 | 电商内容 |
+| 微信公众号 | 微 | 要求封面图 |
+| 中关村在线 | Z | 数码垂直 |
+| 懂车帝 | 懂 | 汽车垂直，要求封面图 |
+
+> 平台列表会随后端配置变化。最新支持平台以桌面客户端 **媒体账号** 页的卡片为准。
+
+## 2. Web 端：媒体管理页
+
+进入 `/media` 后会看到：
+
+### 顶部「浏览器发布器」状态
+
+历史名称为 GEO Publisher 浏览器插件；当前实现已迁移为桌面客户端，但提示文案仍保留以兼容旧用户：
+
+- **插件已连接 / 未连接**
+- **插件版本**、**安装实例 ID**
+- **本地已登录平台** 数量
+- **重新检测** 按钮：触发与桌面客户端的状态同步
+
+### 平台卡片列表
+
+每张平台卡片包含：
+
+- 平台 Logo + 平台名称
+- 当前租户在该平台的绑定数量（**已绑定 N 个账号**）
+- 最近一次同步时间
+- 关键状态徽标：
+  - **已绑定** / **未绑定**
+  - **需要处理**（账号失效、风控、过期）
+  - **本地未登录** / **本地账号不匹配**：桌面客户端登录态异常
+  - **已就绪 / 可发布 / 不可用**
+
+### 操作按钮
+
+- **去绑定 / 重新绑定**：跳转/打开桌面客户端执行真实绑定
+- **解绑**：删除该租户与该账号的关联（需二次确认）。解绑后该账号不再可用于发布，但本地 cookie 仍由桌面客户端控制
+
+> ⚠️ **服务端不存储任何第三方平台 cookie 或 access token**。绑定的本质是把"桌面客户端在该平台的登录态" 与"省心推租户" 关联起来，并把平台 UID、昵称、头像等公开信息同步到 SaaS。
+
+## 3. 在桌面客户端绑定账号
+
+完整步骤见 [桌面客户端 §媒体账号](./09-桌面客户端.md#3-媒体账号)。简版：
+
+1. 桌面客户端左侧导航 → **媒体账号**
+2. 找到目标平台的卡片，点击 **去绑定**
+3. 弹出受控浏览器窗口，自动跳到平台登录页
+4. 在受控窗口里完成账号登录、扫码、短信验证
+5. 客户端检测到登录态后，把 UID、昵称、头像同步回省心推服务端
+6. 回到 Web 端 `/media` 页面 → 卡片状态变为 **已绑定** + **已就绪**
+
+## 4. 发起手动发布
+
+发布动作可以从三处触发：**工作台 → 最近生成 → 发布**、**文章列表 → 发布**、**文章编辑页 → 发布**。三个入口都会打开同一个 **PublishArticleModal** 弹窗。
+
+### 发布弹窗里能做的事
+
+1. **选择发布平台**：弹窗会自动回填"文章里之前选过且当前已绑定"的账号；未绑定/本地登录态异常的平台不可勾选
+2. **上传封面图**：默认关闭；点击 **上传封面图** 后会弹出图片选择器，可从 [图片管理](./07-图片管理.md) 素材库选，也可本地上传
+3. **封面合规校验**：如果你勾选的平台里包含百家号、微信公众号、懂车帝等"必须封面"的平台，没传封面会被拦截，提示「已选择需要封面的发布平台，请先上传封面图」
+4. **提交发布**：服务端把任务派发给当前租户在线的桌面客户端，客户端按平台依次执行真实发布
+
+### 发布状态回写
+
+- 单平台成功：消息 **发布成功**
+- 部分成功：消息 **部分发布失败**，会逐条列出失败平台和原因
+- 全部失败：消息 **发布失败**，提供逐条失败原因
+
+每条发布记录在文章详情抽屉的 **已发布详情** Tab 里能看到：
+
+- **已发布平台**、**发布状态**、**发布时间**
+- **已发布链接**：可 **打开**（在新标签页跳转）或 **复制**
+- 部分平台只有"管理后台"链接（仅有管理页面），在 Web 端会提示"请在客户端打开管理页面查看"
+
+## 5. 平台账号状态规则
+
+| 状态 | 含义 | 处理建议 |
+| --- | --- | --- |
+| **已授权 / 已就绪** | 客户端在线 + 本地登录有效 + 服务端有绑定 | 可直接发布 |
+| **本地未登录** | 服务端有绑定但当前桌面客户端没检测到登录态 | 在客户端重新走一遍登录 |
+| **本地账号不匹配** | 客户端检测到的账号 UID 与服务端绑定不一致 | 在客户端切回正确账号或解绑后重绑 |
+| **需人工验证 / 触发风控** | 平台返回登录态异常 | 在客户端的受控浏览器里完成验证 |
+| **授权过期** | Cookie / Session 失效 | 重新绑定 |
+| **已停用** | 服务端标记为 revoked（如租户主动解绑、违规处理） | 联系管理员 |
+
+## 6. 常见问题
+
+- **Web 端显示已绑定，但发布弹窗里平台不可选**：通常是当前桌面客户端不在线或本地登录态丢失。打开桌面客户端的 **控制台** 确认运行状态，必要时重新检测
+- **部分发布失败但未提示原因**：到文章详情抽屉的 **已发布详情** 看具体失败原因；常见的是平台触发风控、内容触发合规拦截、网络超时
+- **多账号场景**：单平台支持绑定多个账号，发布时弹窗会让你选具体哪个账号

user-manual/06-知识库.md

@@ -0,0 +1,109 @@
+# 知识库
+
+路径 `/knowledge`。知识库用来沉淀品牌资料、产品文档、行业资讯，作为 AI 文章生成时的上下文检索源。**没有官网的品牌，必须先在这里建好公司资料**，否则 AI 在文章生成时拿不到品牌上下文。
+
+## 1. 页面结构
+
+页面分两大块：
+
+- **左侧分组树**：支持一级分组 + 二级子目录两层
+- **右侧内容列表**：所选分组下的全部知识条目
+
+顶部按钮：**添加知识**（默认打开"文档"上传弹窗）。
+
+## 2. 分组管理
+
+### 新建分组
+
+- 左侧 **新建分组**：在根目录下创建一级分组
+- 一级分组的"…"菜单 → **新建子目录**：在该分组下创建二级子目录
+
+> 树最多两层：一级分组 + 子目录。子目录下不能再嵌子目录。
+
+### 编辑 / 删除分组
+
+每个分组节点的"…"菜单都有 **编辑** / **删除**：
+
+- 编辑只改名
+- 删除有强提示：
+  - 删除一级目录会一并删掉它名下的二级目录和全部知识条目
+  - 删除二级目录会一并删掉它名下的全部知识条目
+
+## 3. 添加知识
+
+点击右上角 **添加知识** 弹出的对话框里有三种来源类型：
+
+### 文档（document）
+
+- 支持本地文件批量上传（PDF、Word、Markdown 等）
+- 上传后进入 AI 学习队列；学习完成后可作为生成文章时的检索源
+- 文件大小、格式限制以平台后端为准
+
+### 网站（website）
+
+- 在文本框里粘贴网址，每行一条 URL
+- **单次最多 3 个 URL**：超过会提示「URL 数量超出上限」并禁用提交按钮
+- 后端会异步抓取页面正文 → 入索引 → 对外表现为一条知识条目
+
+### 文本（text）
+
+- 直接粘贴纯文本片段
+- 支持一次提交多条；点击 **+ 添加文本** 可在弹窗里追加
+- 每条需要填 **文本名称**（≤ 20 字）和 **文本内容**
+
+> 添加任何类型的知识前，**必须先创建至少一个分组**，否则会提示「请先创建目录后再新增内容」。
+
+## 4. 内容列表
+
+字段：
+
+| 列 | 说明 |
+| --- | --- |
+| **名称** | 文档名 / 网站标题 / 文本名 |
+| **类型** | 文档 / 网站 / 文本 |
+| **大小** | 字节数（自动单位换算） |
+| **AI 学习** | 状态徽标（见下） |
+| **上传时间** | 创建时间 |
+| **操作** | 重试 / 查看 / 删除 |
+
+### AI 学习状态
+
+| 状态 | 含义 |
+| --- | --- |
+| **待处理** (`pending`) | 已收到但尚未开始解析 |
+| **处理中** (`processing`) | 解析或向量化中 |
+| **学习完成** (`completed`) | 已可被生成模块检索 |
+| **失败** (`failed`) | 解析失败；列表里会显示 **重试** 按钮 |
+| **已删除** (`deleted`) | 已逻辑删除，不再参与生成 |
+
+> 失败原因常见：网页抓取超时、PDF 加密、文档过大被截断。失败后点击 **重试** 重新进队列。
+
+### 操作
+
+- **重试**（仅失败状态可见）：重新触发解析任务
+- **查看**：抽屉式预览原文 + 解析摘要
+- **删除**：二次确认，删除后该条目不再参与文章生成
+
+## 5. 在文章生成里使用知识
+
+知识库与生成模块的连接点：
+
+- **模版向导第 1 步**：选了品牌后，AI 分析阶段会自动检索"该品牌相关的知识条目"作为上下文
+- **仿写创作 → 引用知识库**：可在仿写表单里勾选具体知识条目，作为生成补充参考
+- **自定义生成 / 自由创作**：当前版本不支持显式引用知识库（按品牌检索为隐式行为）
+
+## 6. 起手最佳实践
+
+如果你的品牌没有公司官网，建议至少补齐以下几条：
+
+1. **网站类**：行业头部资讯网站、品牌过往媒体报道（粘贴 URL 即可）
+2. **文档类**：公司介绍 PDF、产品白皮书、品牌故事文档
+3. **文本类**：手写一段品牌定位 + 核心产品列表 + 目标用户描述（300~500 字即可）
+
+把以上三类各放 1~2 条，AI 在写品牌相关文章时就能稳定拿到上下文，效果立竿见影。
+
+## 7. 常见问题
+
+- **添加按钮置灰**：先去左侧创建至少一个分组
+- **网站 URL 提交后一直 pending**：网页站点防爬严格时常见；可考虑把页面正文复制后用「文本」方式重新添加
+- **删除某条知识后文章生成结果没变**：检索结果有缓存，下次新建任务时才会生效

user-manual/07-图片管理.md

@@ -0,0 +1,60 @@
+# 图片管理
+
+路径 `/images`。统一管理图片素材，支持分组、上传去重、引用追踪。文章封面、正文配图、KOL 订阅包封面都从这里调用。
+
+## 1. 页面结构
+
+- 左侧 **文件夹** 列表：包含「全部文件夹」「未分类」 + 自定义文件夹
+- 右侧 **图片网格**：所选文件夹下的图片缩略图
+- 顶部按钮：**上传图片**、搜索框（按名称模糊匹配）
+
+页面右上方还会显示 **存储容量** 进度：「已用 / 总额（百分比）」。容量已满时上传按钮会被拦截，提示「存储空间已满，请清理后再上传」。
+
+## 2. 文件夹管理
+
+- **新建文件夹**：左侧顶部按钮，输入文件夹名后保存
+- **重命名**：在文件夹的右键菜单选 **重命名**
+- **删除文件夹**：
+  - 文件夹为空时直接删除
+  - 文件夹内有图片时会提示「该文件夹内有 X 张图片，这些图片可能已被文章引用。删除文件夹会一并删除这些图片，且不可恢复」
+  - 强制删除按钮：**仍然删除**
+
+## 3. 上传图片
+
+点击 **上传图片**：
+
+- 支持本地多文件上传
+- **去重机制**：上传时若素材库中已有相同 hash 的图片，会自动复用，提示「素材库已有相同图片，已直接复用」（不重复占用存储）
+- 上传完成后图片自动归入当前选中的文件夹（未选中时进 **未分类**）
+
+## 4. 图片操作
+
+把鼠标悬停到任一图片缩略图，会出现操作按钮：
+
+- **重命名**：仅改本地素材库里的展示名，不影响已发布到第三方平台的内容
+- **移动**：把图片移到其他文件夹
+- **删除**：
+  - 如果图片正被文章引用：提示 **图片正在使用中**，并展示哪些文章在引用
+  - 强制删除按钮：**仍然删除**（**会同步影响已绑定文章**，慎用）
+
+## 5. 引用追踪
+
+每张图片支持查看引用关系，分两类：
+
+- **正文引用**：文章正文里的配图
+- **封面引用**：作为文章封面/订阅包封面被引用
+
+> 删除被引用的图片会导致已发布文章里图片链接失效（取决于第三方平台的存储策略）。建议先确认无引用再删除。
+
+## 6. 在哪里会用到这里的图片
+
+- **文章发布弹窗 → 上传封面图 → 选择素材库**：从这里挑封面
+- **自定义生成 / 定时任务 → 封面图**：同样的素材选择器
+- **KOL 订阅包封面**（仅 KOL 角色）：精调模板包的封面图
+- **文章编辑器**：富文本中插入图片时调用
+
+## 7. 常见问题
+
+- **上传一直转圈**：检查 **存储容量** 是否已满；满额时上传会被前端拦截
+- **明明上传了图片，列表里没看到**：上传时未选中文件夹，图片会进 **未分类**；切到 **未分类** 即可看到
+- **图片删了文章里还显示**：第三方平台已发布的内容里图片不会随之消失，但本地素材库里再次发布时会失败

user-manual/08-数据追踪.md

@@ -0,0 +1,139 @@
+# 数据追踪
+
+路径 `/tracking`，对应左侧导航 **数据追踪 → 数据详情**。这是省心推 GEO 价值的核心呈现位：在豆包、文心一言、通义千问、DeepSeek、Kimi、混元/元宝等 AI 平台上采样品牌相关问题的真实回答，归因引用来源，量化品牌曝光。
+
+## 1. 数据来源
+
+数据**不是从第三方搜索引擎抓的**，而是由桌面客户端直接打开 AI 平台对话页、按问题集逐条采样：
+
+- 每个 **品牌 → 关键词 → 问题** 都是一次采样单位
+- 桌面客户端每天按计划运行采样任务，把模型回答和引用来源回写到服务端
+- 你也可以在页面里手动 **立即采集**
+
+> 数据采集前置条件（缺一项就拿不到数据）：
+> 1. 当前账号已在桌面客户端登录、且客户端**在线**
+> 2. 桌面客户端的 **AI 平台** 页面已绑定至少一个 AI 平台并 **授权正常**
+> 3. 品牌词库里已建好品牌 → 关键词 → 至少一个问题
+
+## 2. 页面结构
+
+进入 `/tracking` 后顶部是筛选区：
+
+- **品牌**：必选；账号下没品牌时整页空
+- **关键词**：可选，限定到具体关键词
+- **AI 平台筛选**：聚焦看某个平台的表现
+- **立即采集** 按钮：仅当上述前置条件全部满足时可点
+
+页面主体分为四块：
+
+### A. 平台对比矩阵
+
+横向把当前所有 AI 平台并排，纵向是品牌相关指标。能直观看到：
+
+- 哪些平台经常引用我？
+- 哪些平台一次没引用？
+- 同一个问题在不同平台上的回答差异
+
+### B. 高频问题
+
+按品牌库当前关键词下的问题集排序展示：
+
+- 显示问题文本、最近一次采样时间
+- 点击任一问题进入 **问题详情页**
+
+### C. 引用排行（Citation Ranking）
+
+按发布外链主体归因 SaaS 发文在模型引用来源中的出现次数与占比：
+
+- 时间窗口：**近 7 天 / 近 30 天** 切换
+- 字段：来源域名、引用次数、占比
+- 视图说明：「按发布外链主体归因 SaaS 发文在模型引用来源中的出现次数与占比」
+
+### D. 被引用文章（Cited Articles）
+
+横向列出被任意 AI 平台引用过的省心推平台内文章：
+
+- 字段：文章标题、被引用次数、最近被引平台
+- 点击文章可进入文章详情抽屉
+
+## 3. 问题详情页
+
+路径 `/tracking/questions/:brandId/:questionId`。这是省心推数据回看的最深层级，分四块：
+
+### 答案内容（Answer Content）
+
+- 选中的 AI 平台对该问题的最新回答全文
+- 没有采样数据时显示「该平台暂无采样回答」
+
+### 引用来源（Citation Sources）
+
+- 模型回答里附带的所有外部链接
+- 字段：序号 + 链接 + 域名
+- 每条引用来源右侧有 **仿写创作** 按钮：一键把这条外链作为来源导入仿写流程（详见 [文章创作 §仿写创作](./03-文章创作.md#4-仿写创作)）
+
+### 引用分析（Citation Analysis）
+
+- 服务端基于回答内容做的归因分析
+- 试图回答"为什么模型在这个问题上引用了这些来源"
+
+### 内容引用（Content Citations）
+
+- 当前账号已发布的文章在该问题里被引用的次数
+- 用于直接验证"我们写的文章是否被 AI 引用了"
+
+## 4. 立即采集
+
+立即采集会触发桌面客户端马上跑一次该品牌（或具体关键词/问题）的采样任务。可点击场景：
+
+- 当天日期 + 客户端在线 + AI 平台授权正常 + 至少一个问题已建立
+
+不可点击的常见原因：
+
+| 提示 | 解释 |
+| --- | --- |
+| 「请先选择品牌，再发起采集」 | 顶部筛选未选品牌 |
+| 「请先选择关键词，再立即采集当前问题」 | 在问题详情页未限定关键词 |
+| 「立即采集只支持今天的数据，请切回今天后再操作」 | 数据查询区切到了历史日期 |
+| 「正在检查当前账号的桌面客户端状态」 | 客户端心跳中，稍等 |
+| 「当前登录账号的桌面客户端未在线，暂时不能立即采集」 | 桌面端没启动或网络中断 |
+| 「当前账号尚未注册桌面客户端，不能发起采集」 | 没装客户端、或客户端没用同一账号登录过 |
+| 「当前账号暂无已授权 AI 平台，不能发起采集」 | 桌面端 AI 平台页面没绑定任何平台 |
+| 「当前筛选平台未授权，不能发起采集」 | 筛选了某个平台，但该平台没授权 |
+
+## 5. 采集模式与覆盖率
+
+页面顶部信息条会展示：
+
+```
+插件采样 · 目标 X · 计划 Y · 已采样 Z · 覆盖率 A% · 更新于 ... · 触发方式
+```
+
+字段含义：
+
+- **目标**：原计划要采样的次数
+- **计划**：实际生成的采集任务数
+- **已采样**：成功回写结果的次数
+- **覆盖率**：已采样 / 目标
+- **触发方式**：周期任务 / 立即采集
+
+> 插件模式（实际为桌面客户端模式）下结果受设备在线率影响，**低覆盖样本仅供趋势参考**。建议保持桌面客户端长期在线以提升覆盖率。
+
+## 6. 平台授权状态横幅
+
+页面顶部会显示授权状态卡片：
+
+| 状态 | 含义 | 后续动作 |
+| --- | --- | --- |
+| **AI 平台授权正常** | 已有可用授权 | 可正常采样 |
+| **未检测到桌面客户端** | 当前账号没在桌面客户端登录过 | 安装并登录桌面客户端 |
+| **暂无已授权 AI 平台** | 客户端有，但 AI 平台未绑定 | 桌面端 → AI 平台 → 绑定 |
+
+## 7. 异步任务调试
+
+页面底部有一块 **异步任务调试**，仅用于排查 callback → 队列 → worker 的流转，不影响上方四块主内容。一般用户可忽略；遇到数据延迟或缺失时可截图给运营同学看。
+
+## 8. 常见问题
+
+- **页面常年空白**：99% 的情况是缺前置条件之一（品牌 / 问题 / 桌面客户端 / AI 平台授权）
+- **某个 AI 平台总是没数据**：去桌面端 **AI 平台** 页面看该平台的授权状态；常见是 cookie 过期需要重新授权
+- **引用排行里没看到自己的文章**：归因按"发布外链主体"匹配；要确认文章已发布到第三方平台并产生了外链，且模型在采样窗口内引用了这条外链

user-manual/09-桌面客户端.md

@@ -0,0 +1,146 @@
+# 桌面客户端
+
+桌面客户端（Electron 应用）是省心推执行**真实操作**的地方：媒体账号绑定、AI 平台授权、文章发布、AI 数据采集都在这里运行。Web 端只是查询和配置入口。
+
+## 1. 安装与登录
+
+1. 从运营或管理员处获取桌面客户端安装包（macOS / Windows）
+2. 安装后启动，首屏是登录页：与 Web 端使用**完全相同**的账号登录
+3. 登录成功后侧边栏出现 4 个导航项：
+
+| 入口 | 用途 |
+| --- | --- |
+| **控制台** | 运行总览、活动流、健康度 |
+| **发布管理** | 待发布队列、历史发送结果、重试 |
+| **媒体账号** | 13 个发布平台的授权与多账号管理 |
+| **AI 平台** | 6 个 AI 对话平台的绑定与授权 |
+
+侧边栏底部展示当前登录的操作员、邮箱、设备名（client）。设置入口为右下角图标，会另开独立设置窗口。
+
+## 2. 控制台（首页）
+
+路径 `/`。汇总展示：
+
+- **总体健康度**：服务连接、心跳、单点事件流、调度节点、任务消费端
+- **本地账号同步**事件：每次同步成功/失败都会记录
+- **任务流事件**：任务领取、执行成功、执行失败、租约续期失败、令牌过期等
+- **未完成问题**列表：任务执行失败、账号需要人工验证、触发风控等异常会聚合到这里
+
+> 控制台事件是英文事件名+本地化文案双显示。如果看到全英文事件名，说明翻译表里还没收录这条事件，可保留截图反馈。
+
+## 3. 媒体账号
+
+路径 `/media-platforms`。
+
+### 顶部概览
+
+- **已授权数**、**待处理数**、**风险观察数**、**在线客户端数** 四个总览数
+
+### 平台卡片
+
+按 13 个发布平台并排陈列，每张卡片显示：
+
+- 平台 Logo、名称、缩写、品牌色
+- 当前已绑定账号数
+- 最近一个账号的状态、UID、昵称、最后校验时间
+
+### 平台筛选
+
+- **平台**：全部 / 单平台
+- **状态**：全部 / 已授权 / 待处理 / 风险观察 / 授权过期
+- **搜索框**：按账号昵称或 UID
+
+### 操作
+
+- **去绑定 / 重新绑定**：在受控浏览器里打开平台登录页，登录成功后客户端识别 cookie + UID，回写到 SaaS
+- **打开平台**：直接在受控浏览器里打开该平台后台
+- **重新检测**（探测）：单账号触发一次状态校验
+- **重新授权**：账号过期时使用，等价于"重新登录"
+- **解绑**：断开 SaaS 与该账号的关联（本地 cookie 仍保留）
+
+### 状态徽标
+
+| 状态 | 含义 |
+| --- | --- |
+| **已授权** | 正常，可发布 |
+| **授权过期** | Cookie/Session 失效，需重新授权 |
+| **触发风控** | 平台返回风控挑战，需要人工在受控浏览器完成验证 |
+| **需人工验证** | 与风控类似，多为短信、扫码二次验证 |
+| **已停用** | 服务端 revoke |
+| **等待校验 / 校验中** | 探测任务排队或执行中 |
+| **最近校验失败** | 网络问题，重试即可 |
+
+## 4. AI 平台
+
+路径 `/ai-platforms`。
+
+### 当前支持的 AI 平台（6 个）
+
+- **豆包**（doubao）
+- **文心一言**（wenxin）
+- **通义千问**（qwen）
+- **DeepSeek**（deepseek）
+- **Kimi**（kimi）
+- **混元 / 元宝**（yuanbao）
+
+每个平台**只允许绑定一个账号**（与发布媒体不同），但绑定后即可用于全部品牌的 AI 数据采样。
+
+### 卡片字段
+
+- 平台名称 + 简介
+- 绑定状态徽标：**未绑定 / 授权正常 / 授权过期 / 需人工验证 / 触发风控 / 已停用 / 待校验**
+- 已绑定账号的 UID、最后校验时间
+- 操作按钮：**去绑定 / 重新授权 / 打开平台 / 解绑**
+
+### 顶部总览
+
+- **已配置平台数**、**已绑定数**、**当前在线数**、**在线客户端数**
+
+> AI 平台不能发布文章，只用于数据采集。绑定流程与媒体账号一致：受控浏览器登录 → 客户端识别 cookie → 回写服务端。
+
+## 5. 发布管理
+
+路径 `/publish-management`。集中查看发布任务队列与历史。
+
+### 列表字段
+
+- 文章标题、目标平台、目标账号
+- 任务状态：**等待发布** / **正在发送** / **发布成功** / **发布失败** / **结果未知**
+- 已发送链接、错误信息、合规拦截记录
+- 重试次数、租约到期时间、创建/更新时间
+
+### 操作
+
+- **再次发送**：失败任务可重试；会创建新任务记录
+- **打开链接**：成功任务的外链
+- **复制错误信息**：把脱敏后的错误详情复制出来报障
+
+### 自动刷新
+
+发布管理列表会按固定间隔（PAGE 内部计时）自动刷新，无需手动操作。
+
+## 6. 设置（独立窗口）
+
+点击侧边栏底部 **设置** 图标会弹出独立窗口，分四块：
+
+- **通用**：开机自启 / 保持后台运行
+- **登录设置**：服务端 API 地址（默认指向生产环境，未修改不要动）
+- **诊断**：导出 runtime 快照（包含子系统状态、客户端列表、版本号）用于报障
+- **关于 GEO**：版本号、客户端 ID
+
+> 修改服务端地址后需要重启客户端生效。仅在切换内部测试环境时需要修改。
+
+## 7. 客户端常见状态
+
+- **客户端不在线**：Web 端发布弹窗会标灰、立即采集会被拦截。打开桌面客户端，控制台会显示连接状态
+- **令牌过期**：控制台事件流会出现「客户端令牌已过期」，重新登录即可
+- **心跳失败 / 单点事件流退避**：网络抖动；通常自动恢复，不超过 30 秒应该回到正常
+- **任务领取失败 / 兜底拉取失败**：消息队列异常时会自动走数据库兜底；如果持续失败请联系平台
+
+## 8. 多设备同账号
+
+同一个账号可以在多台设备上登录桌面客户端。在线客户端数会显示在控制台和侧边栏。多台同时在线时：
+
+- 发布任务会被某一台领取并执行（避免重复）
+- AI 数据采集任务也按设备分流
+- 媒体账号绑定相互独立：A 机器绑定的知乎账号，不会自动出现在 B 机器

user-manual/10-精调模板与KOL.md

@@ -0,0 +1,122 @@
+# 精调模板与 KOL 工作区
+
+精调模板（KOL Refined Templates）是省心推区别于普通通用模版的高阶能力：行业 KOL 把自己沉淀的高质量提示词打包成订阅包，挂到「精调模板市场」，租户订阅后即可直接用 KOL 的精调 Prompt 生成内容。
+
+本章分两部分：**所有租户**都能看到的精调模板市场（订阅方）；**KOL 角色**才能看到的 KOL 工作区（供给方）。
+
+## 1. 精调模板市场（订阅方）
+
+路径 `/kol/marketplace`，左侧导航 **精调模板市场**。
+
+### 列表筛选
+
+顶部筛选区：
+
+- **行业**：按 KOL 标注的行业过滤
+- **关键字**：模糊搜索包名/KOL 名称
+- **全部 / 已订阅 / 未订阅**：按订阅状态过滤
+
+### 订阅包卡片
+
+每张卡片包含：
+
+- 封面图（KOL 上传）
+- 包名 + 标签
+- KOL 显示名 + 头像
+- 订阅租户数 + 提示词数
+- 订阅状态徽标：**未订阅** / **审核中** / **已订阅** / **已撤销** / **已到期**
+- 价格说明（KOL 自定义文案，比如"联系我获取报价"）
+
+点击卡片进入 **订阅包详情** 页 `/kol/packages/:id`。
+
+### 申请订阅
+
+订阅包详情页：
+
+- 顶部：包基本信息 + 订阅状态
+- 下方：该包内的提示词清单（每条带名称、平台、变量预览）
+- 操作：**申请订阅** 按钮（未订阅时可见）
+
+申请提交后状态变为 **审核中**。KOL 在自己的提示词管理页通过后，状态变为 **已订阅**，租户即可在工作台看到对应的精调模板卡片。
+
+### 使用精调模板
+
+订阅成功后两个入口可触发生成：
+
+- **工作台 → 精调模版区**：点击卡片直接进 `/kol/generate/:subscriptionPromptId`
+- **模版创作列表 → 精调模版区**：点击模版名进入向导
+
+精调模板生成页只展示该提示词需要填的变量，例如：
+
+- 输入框（input）、多行文本（textarea）、选择框（select）、数字框（number）、多选框（checkbox）
+
+填好变量点击 **生成** → 任务进入队列 → 完成后回到列表。
+
+## 2. KOL 工作区（仅 KOL 角色可见）
+
+如果当前账号被授权为 KOL，左侧导航底部会出现 **KOL 工作区**，包含三个页面：
+
+- **提示词管理**（`/kol/manage`）
+- **数据看板**（`/kol/dashboard`）
+- **个人主页**（`/kol/profile`）
+
+### 提示词管理
+
+页面左右分栏：
+
+#### 左侧：订阅包
+
+- **创建订阅包**：填写包名、标签、价格说明、封面图（可从素材库选或本地上传）
+- **编辑包** / **发布** / **归档** / **删除**
+- 状态：**草稿** / **已发布** / **已归档**
+
+#### 右侧：提示词
+
+- **新增提示词**：选所属包后填写提示词内容（支持 Markdown）、平台、变量定义
+- **AI 生成**：填一段需求描述，让大模型帮你生成 prompt 初稿
+- **AI 优化**：选中一段已有 prompt，让 AI 优化为更清晰的版本（注意：会消耗 AI 点数，详见 [AI 点数](./11-AI点数与套餐.md)）
+- **预览表单**：模拟订阅方填写时的表单效果
+- **保存草稿** / **发布** / **上线 / 下线**
+- 状态：**草稿** / **已上线** / **已下线**
+
+#### 变量定义
+
+每个变量需要配置：
+
+- **变量 key**：模板里的占位符
+- **显示名**：表单里的字段标签
+- **类型**：输入框 / 多行文本 / 选择框 / 数字框 / 多选框
+- **必填**、**提示语（placeholder）**、**字数限制**、**默认值**
+- 选择框：**选项**（逗号分隔）
+- 数字框：**最小数字 / 最大数字 / 默认数字**
+
+### 数据看板
+
+`/kol/dashboard`，按订阅包维度展示：
+
+- **总订阅租户数** / **本月新增**
+- **总使用次数** / **本月使用**
+- **失败率**
+- **按包维度**：每个包的使用情况
+- **趋势图**：近期数据走势
+
+### 个人主页
+
+`/kol/profile`：
+
+- **显示名**、**简介**、**头像**
+- 联系方式、专业领域标签、行业标签
+- 此处信息**公开展示在精调模板市场**，与账号设置无关（账号信息在右上角的个人菜单里）
+
+## 3. 订阅与权限规则
+
+- 订阅包必须先 **发布** 才会出现在市场里
+- 订阅审核当前为 KOL 手动审核（KOL 在提示词管理 → 订阅包详情可看到申请列表，决定通过或拒绝）
+- 包被 **归档** 后，已订阅租户的 **已订阅** 状态会变为 **已撤销**，不再可以新建生成任务，但历史文章保留
+- 提示词 **下线** 后，订阅租户工作台不会再展示该模板卡片，但已发起的任务会跑完
+
+## 4. 常见问题
+
+- **没看到 KOL 工作区导航**：当前账号未被授权为活跃 KOL；联系运营开通
+- **创建订阅包后市场里看不到**：订阅包默认是 **草稿** 状态，需要点击 **发布**
+- **AI 生成/优化按钮置灰**：AI 点数余额不足；详见 [AI 点数](./11-AI点数与套餐.md)

user-manual/11-AI点数与套餐.md

@@ -0,0 +1,104 @@
+# AI 点数与套餐
+
+省心推用 **AI 点数** 作为内部计费单位，覆盖各类 AI 调用（文章生成、模板分析、片段优化等）。本章只讲点数与套餐的可见行为；具体计费公式以平台财务规则为准。
+
+## 1. 在哪里看点数
+
+### 个人中心 → AI 点数明细
+
+路径 `/account/ai-points`。页面包含：
+
+- **可用点数**（balance）：当前剩余可消耗点数
+- **基准字数**（baseChars）：当前套餐的「每 N 字消耗 1 点」基准
+- **消耗流水**：最近几条点数变动记录
+
+### Web 端右上角侧边栏
+
+侧边栏底部"套餐与额度"区域聚合显示：
+
+- **当前套餐**（如 免费版）+ **状态正常**
+- **会员到期** 时间
+- **生成文章** 配额（剩余/总额）
+- **AI 点数** 余额
+- **重置时间**：免费版的配额重置周期
+
+## 2. 点数消耗规则
+
+### 计费基础
+
+- 每个 AI 调用按"请求字数 / 基准字数"换算成点数
+- 套餐越高，**基准字数** 越大（同样请求消耗的点数越少）
+- 流水里能看到「{字数} 字 / 基准 {基准}」的换算说明
+
+### 预占与确认
+
+AI 任务在提交时会**先预占**对应点数，任务完成后才正式确认扣除：
+
+| 状态 | 含义 |
+| --- | --- |
+| **处理中**（pending） | 已预占，等待结果 |
+| **已扣除**（completed） | 任务成功，正式扣除 |
+| **已退回**（refunded） | 任务失败，预占点数原路退回 |
+| **失败**（failed） | 任务失败但点数处理异常（少见） |
+
+> 预占机制保证你不会"跑了一半发现点数不够"，但同时也意味着排队任务会占用余额。
+
+## 3. 点数消耗场景
+
+每条流水会带 **使用场景** 标签，常见的：
+
+| 场景代号 | 中文显示 | 对应行为 |
+| --- | --- | --- |
+| `template_analyze` | AI 分析 | 模版向导第 1 步的 AI 品牌分析（关键词/竞品/标题候选） |
+| `template_title_generate` | AI 生成标题 | 模版向导第 2 步生成 5 个标题候选 |
+| `template_outline_generate` | AI 生成大纲 | 模版向导第 3 步生成完整大纲 |
+| `article_selection_optimize` | 文章片段优化 | 文章编辑器里选中段落让 AI 改写 |
+| `kol_prompt_generate` | KOL 模版生成 | KOL 管理页用 AI 帮你写一段 prompt 初稿 |
+| `kol_prompt_optimize` | KOL 模版优化 | KOL 管理页让 AI 优化已有 prompt |
+
+> 注意：模版生成的"正文"消耗主体在 **生成额度**（按文章篇数计），AI 分析/标题/大纲走的是 AI 点数。两者是分开计量的。
+
+## 4. 套餐与配额
+
+侧边栏的"套餐与额度"区域展示当前套餐核心配额：
+
+- **生成文章**：按月或周期计；用尽后无法再发起新生成任务
+- **AI 点数**：可用余额
+- **重置时间**：免费版的配额重置时间点
+
+更细的配额（品牌数上限、关键词总数、单关键词问题数）在 [品牌词库](./04-品牌词库.md) 页面顶部条形展示。
+
+### 配额耗尽时的提示
+
+- **生成文章额度用尽**：发起任务时弹窗提示，并引导查看升级入口
+- **AI 点数不足**：AI 分析、标题生成、大纲生成等按钮置灰，提示"点数不足"
+- **品牌/关键词/问题数到上限**：新建按钮置灰，提示具体上限值
+
+## 5. 流水排查
+
+进入 **AI 点数明细** 页查看流水：
+
+- **使用场景**：哪类操作触发的扣点
+- **点数**：本次消耗（负数表示扣除，正数表示退回）
+- **计费字数**：实际请求字数
+- **创建时间**、**状态**
+
+如果有"莫名其妙的扣点"：
+
+1. 看流水里的 **使用场景**，对照表确认是哪个动作触发的
+2. 看 **状态**，**已退回** 表示任务失败已退还，无需关注
+3. 单条扣点异常偏高时，把流水截图反馈给运营/管理员
+
+## 6. 升级套餐
+
+侧边栏"套餐与额度"区域提供升级入口（按租户配置可能为占位）。当前主要由销售/管理员人工对接。升级后：
+
+- 配额（品牌/关键词/问题/文章/点数）实时生效
+- 已有任务的预占、流水保留不变
+- 旧版本套餐的配额不会"翻新"（即不会自动多送月初配额）
+
+## 7. 常见问题
+
+- **点数不够但工作台还能点生成**：因为前端只在提交时校验余额，进入向导前不拦截。提交时如果点数不足才会拒绝
+- **任务失败了，但点数还是扣了**：核对流水里对应记录的 **状态**；正常应该是 **已退回**。如果显示 **失败**（极少见）或仍是 **已扣除**，请提工单
+- **看不到 AI 点数明细**：需要登录态正常 + 当前账号有 AI 用量记录才会展示流水；从未触发 AI 调用的全新账号会显示「暂无 AI 点数流水」

user-manual/12-常见问题.md

@@ -0,0 +1,172 @@
+# 常见问题
+
+按场景归类的故障排查。每条 FAQ 都包含「现象 → 排查 → 处理」三段。
+
+## 一、登录与账号
+
+**Q：登录页输入手机号/邮箱+密码后一直转圈**
+
+- 检查浏览器控制台是否有跨域或 401 报错
+- 确认账号未被禁用：联系运营/管理员核对状态
+- 清除浏览器 Cookie 后重试
+
+**Q：登录后没有 KOL 工作区**
+
+- KOL 工作区只对"活跃 KOL"角色显示
+- 联系运营开通 KOL 资质，重新登录即可
+
+## 二、品牌、关键词、问题
+
+**Q：新建品牌按钮置灰**
+
+- 顶部"品牌公司"配额已到上限
+- 免费版默认 1 个、付费版默认 2 个；联系运营升级或删掉旧品牌
+
+**Q：模版向导里的"AI 分析"结果总是空**
+
+- 确认品牌"公司官网"已填，或 [知识库](./06-知识库.md) 里已有该品牌资料
+- 二者都没有时 AI 拿不到品牌上下文，是预期行为
+
+**Q：新建关键词提示"已用完"**
+
+- 总关键词数受套餐限制；删旧关键词或升级套餐
+
+**Q：单关键词加问题到不了 N 个**
+
+- 套餐对单关键词问题上限有约束；顶部进度条会显示「问题 X / Y」
+
+## 三、模版与生成
+
+**Q：提交生成后任务一直 generating**
+
+- 前端每 10 秒自动轮询。等 1~2 分钟仍无变化时：
+  - 看 [AI 点数](./11-AI点数与套餐.md) 是否余额足够
+  - 看 [桌面客户端](./09-桌面客户端.md) 控制台是否有任务执行失败事件
+- 仍未恢复请提工单
+
+**Q：生成结果质量差**
+
+- 检查模版向导第 1 步是否选了品牌；没选时 AI 拿不到上下文
+- 在第 1 步点 **分析**，确认品牌摘要、关键词、竞品都补齐了
+- 在第 3 步"关键要点"里补充更具体的卖点和风格要求
+
+**Q：AI 分析按钮一直转**
+
+- 服务端在跑 LLM 调用，1~5 秒为正常；超过 30 秒未返回时刷新页面重试
+- 反复失败时优先检查 AI 点数余额
+
+## 四、媒体绑定与发布
+
+**Q：Web 端 `/media` 显示已绑定，但发布弹窗里平台不可选**
+
+- 99% 是当前桌面客户端不在线
+- 打开桌面客户端 → 控制台确认连接正常
+- 控制台显示"令牌过期"时重新登录客户端
+
+**Q：发布到某个平台一直失败**
+
+- 在 [桌面客户端 → 发布管理](./09-桌面客户端.md#5-发布管理) 看具体错误信息
+- 常见原因：
+  - **触发风控**：到桌面客户端 → 媒体账号 → 重新授权
+  - **内容合规拦截**：第三方平台拒收，调整正文后重发
+  - **网络超时**：直接 **再次发送**
+
+**Q：发布弹窗提示"已选择需要封面的发布平台，请先上传封面图"**
+
+- 微信公众号、百家号、懂车帝等平台强制要求封面
+- 点击 **上传封面图** → 从素材库选或本地上传
+
+**Q：单平台支持绑定多个账号吗**
+
+- 支持。发布弹窗会让你选具体哪个账号
+- AI 平台不支持多账号，每个 AI 平台只能绑定一个账号
+
+## 五、数据追踪
+
+**Q：进入数据追踪页面常年空白**
+
+按以下顺序排查：
+
+1. 顶部筛选有没有选 **品牌**
+2. 该品牌在 [品牌词库](./04-品牌词库.md) 是否建了关键词
+3. 关键词下是否建了问题
+4. [桌面客户端](./09-桌面客户端.md) 是否在线（看在线客户端数）
+5. 桌面客户端 **AI 平台** 页是否绑定了至少一个平台且授权正常
+
+**Q：某个 AI 平台始终没数据**
+
+- 桌面客户端 **AI 平台** 页面看该平台状态
+- 状态为"授权过期 / 触发风控 / 需人工验证"时，点 **重新授权** 处理
+
+**Q：立即采集按钮置灰**
+
+- 把鼠标悬停在按钮上看 Tooltip 提示，会指出具体阻塞原因（参见 [数据追踪 §立即采集](./08-数据追踪.md#4-立即采集) 的对照表）
+
+## 六、知识库
+
+**Q：网站类知识一直 pending**
+
+- 部分网站防爬严格，抓取超时
+- 改用 **文本** 类型，把页面正文复制后再粘贴
+
+**Q：上传 PDF 后失败**
+
+- 加密 PDF 不支持
+- 文档过大会被截断；建议拆成多个小文件
+- 失败的条目可点击 **重试** 按钮重新进队列
+
+**Q：删除知识条目后 AI 还在引用**
+
+- 检索结果有缓存，下次新建任务时才会生效
+
+## 七、桌面客户端
+
+**Q：桌面客户端启动后控制台一直红**
+
+- 检查网络是否能访问省心推服务端（设置 → 登录设置 里的 API 地址）
+- 检查系统时间是否准确（差 5 分钟以上可能导致 token 校验失败）
+- 仍然不行：诊断页 → 复制运行快照 → 反馈
+
+**Q：客户端登录提示"令牌过期"**
+
+- 直接退出后重新登录即可
+- 频繁出现时检查是否有多设备同账号互踢
+
+**Q：客户端任务领取失败 / 兜底拉取失败**
+
+- 通常是消息队列瞬时抖动；客户端会自动走兜底拉取，等 30 秒一般会恢复
+- 持续 5 分钟以上未恢复时联系运营
+
+## 八、AI 点数
+
+**Q：任务失败后点数没退回**
+
+- 流水里对应条目状态应该变为 **已退回**
+- 如果 30 分钟内仍是 **处理中**，提工单
+- 如果显示 **已扣除**（极少见），把流水 ID 截图反馈
+
+**Q：点数怎么扣那么快**
+
+- 模版向导每一步的 AI 操作（分析、标题、大纲）都会单独扣一次
+- 开了 **AI 优化**、**AI 生成 prompt** 功能后会快速消耗
+- 想节流时：跳过非必要的 AI 分析（手动填写关键词与竞品也可以）
+
+## 九、报障流程
+
+把以下信息收集好，能让运营定位问题快 10 倍：
+
+1. **当前账号手机号或邮箱**
+2. **报错时间**（精确到分钟）
+3. **操作步骤**（到了哪个页面，点了什么按钮）
+4. **报错截图**：含 URL 栏 + 错误提示 + 浏览器 DevTools Console（如果有红色报错）
+5. **桌面客户端版本号**（设置 → 关于 GEO）+ 控制台事件流截图（如果是发布/采集类问题）
+
+## 十、文档反馈
+
+如果在使用本手册过程中发现：
+
+- 描述与控制台实际行为不一致
+- 漏掉了某个常见操作场景
+- 截图/示意图不够清晰
+
+请直接联系本租户的省心推管理员或对接运营。控制台代码会持续迭代，文档也会同步更新。

user-manual/README.md

@@ -0,0 +1,41 @@
+# 省心推 用户手册
+
+省心推是一款面向品牌运营、内容编辑和数字营销团队的 GEO 内容运营平台。它围绕 AI 内容生成、品牌资产沉淀、媒体账号绑定、手动发布和数据回看五条主链路，帮助你在豆包、文心一言、通义千问、DeepSeek、Kimi、混元/元宝等 AI 搜索场景下产出可被引用的高质量内容。
+
+本手册适用对象：
+
+- 品牌方 / 内容运营 / 数字营销人员
+- 项目内的管理员和只读成员
+- 首次接触省心推的新用户
+
+> 本手册以当前线上代码为准。若控制台界面与文档存在差异，以控制台实际行为为准。
+
+## 目录
+
+1. [入门指南（必读）](./01-入门指南.md) — 登录、起步五步走、品牌资料起手式
+2. [工作台](./02-工作台.md) — 数据总览、模版入口、最近生成
+3. [文章创作](./03-文章创作.md) — 模版创作、自定义生成、自由创作、仿写创作
+4. [品牌词库](./04-品牌词库.md) — 品牌、关键词、问题集、竞品库
+5. [媒体管理与发布](./05-媒体管理与发布.md) — 平台清单、绑定流程、手动发布
+6. [知识库](./06-知识库.md) — 文档 / 网站 / 文本三类来源
+7. [图片管理](./07-图片管理.md) — 素材分组、上传、引用追踪
+8. [数据追踪](./08-数据追踪.md) — AI 平台采集、平台矩阵、引用归因
+9. [桌面客户端](./09-桌面客户端.md) — 控制台、发布队列、媒体账号、AI 平台
+10. [精调模板与 KOL 工作区](./10-精调模板与KOL.md) — 订阅市场、提示词管理、数据看板
+11. [AI 点数与套餐](./11-AI点数与套餐.md) — 点数计费、配额重置、消耗流水
+12. [常见问题](./12-常见问题.md) — 故障排查 FAQ
+
+## 名词约定
+
+| 术语 | 含义 |
+| --- | --- |
+| Web 端（控制台） | 浏览器中打开的省心推主控台 |
+| 桌面客户端 | 安装在本地的 Electron 应用，承担媒体登录、AI 平台采集、真实发布执行 |
+| 媒体账号 | 用户在第三方发布平台（如知乎、头条号）上的登录账号 |
+| AI 平台 | 用于 GEO 数据采集的大模型对话平台（豆包、文心一言等） |
+| 生成任务 | 一次 AI 文章生成请求，含模版、自定义、仿写多种来源 |
+| AI 点数 | 按"基准字数"计费的内部消耗单位，覆盖标题/大纲/分析/优化等 AI 调用 |
+
+## 一句话起步
+
+新用户登录后，请按以下顺序操作：**先去品牌词库建好品牌（无官网必须先到知识库补公司资料）→ 添加关键词与每个关键词下 1~2 个核心问题 → 安装桌面客户端 → 在客户端绑定至少一个发布平台和一个 AI 平台 → 回到工作台用模版生成文章 → 在文章列表点击发布**。完整流程见 [入门指南](./01-入门指南.md)。