diff --git a/user-manual/01-入门指南.md b/user-manual/01-入门指南.md
new file mode 100644
index 0000000..eee5924
--- /dev/null
+++ b/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) 排查具体故障会更顺手。
diff --git a/user-manual/02-工作台.md b/user-manual/02-工作台.md
new file mode 100644
index 0000000..2816030
--- /dev/null
+++ b/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，会跨页面缓存；切到 **品牌词库** 或 **媒体管理** 操作完成后，回到工作台会自动刷新。如果还不一致，点击最近生成右上角的 **刷新** 按钮强制拉取。
diff --git a/user-manual/03-文章创作.md b/user-manual/03-文章创作.md
new file mode 100644
index 0000000..d14c590
--- /dev/null
+++ b/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 秒一次
diff --git a/user-manual/04-品牌词库.md b/user-manual/04-品牌词库.md
new file mode 100644
index 0000000..f0cee62
--- /dev/null
+++ b/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 拿不到上下文
+- **删除品牌后数据追踪还能看见旧数据**：数据快照不会随删除一起清理，会按窗口期自然过期
diff --git a/user-manual/05-媒体管理与发布.md b/user-manual/05-媒体管理与发布.md
new file mode 100644
index 0000000..9532905
--- /dev/null
+++ b/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 端显示已绑定，但发布弹窗里平台不可选**：通常是当前桌面客户端不在线或本地登录态丢失。打开桌面客户端的 **控制台** 确认运行状态，必要时重新检测
+- **部分发布失败但未提示原因**：到文章详情抽屉的 **已发布详情** 看具体失败原因；常见的是平台触发风控、内容触发合规拦截、网络超时
+- **多账号场景**：单平台支持绑定多个账号，发布时弹窗会让你选具体哪个账号
diff --git a/user-manual/06-知识库.md b/user-manual/06-知识库.md
new file mode 100644
index 0000000..41c388d
--- /dev/null
+++ b/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**：网页站点防爬严格时常见；可考虑把页面正文复制后用「文本」方式重新添加
+- **删除某条知识后文章生成结果没变**：检索结果有缓存，下次新建任务时才会生效
diff --git a/user-manual/07-图片管理.md b/user-manual/07-图片管理.md
new file mode 100644
index 0000000..e0a074b
--- /dev/null
+++ b/user-manual/07-图片管理.md
@@ -0,0 +1,60 @@
+# 图片管理
+
+路径 `/images`。统一管理图片素材，支持分组、上传去重、引用追踪。文章封面、正文配图、KOL 订阅包封面都从这里调用。
+
+## 1. 页面结构
+
+- 左侧 **文件夹** 列表：包含「全部文件夹」「未分类」 + 自定义文件夹
+- 右侧 **图片网格**：所选文件夹下的图片缩略图
+- 顶部按钮：**上传图片**、搜索框（按名称模糊匹配）
+
+页面右上方还会显示 **存储容量** 进度：「已用 / 总额（百分比）」。容量已满时上传按钮会被拦截，提示「存储空间已满，请清理后再上传」。
+
+## 2. 文件夹管理
+
+- **新建文件夹**：左侧顶部按钮，输入文件夹名后保存
+- **重命名**：在文件夹的右键菜单选 **重命名**
+- **删除文件夹**：
+  - 文件夹为空时直接删除
+  - 文件夹内有图片时会提示「该文件夹内有 X 张图片，这些图片可能已被文章引用。删除文件夹会一并删除这些图片，且不可恢复」
+  - 强制删除按钮：**仍然删除**
+
+## 3. 上传图片
+
+点击 **上传图片**：
+
+- 支持本地多文件上传
+- **去重机制**：上传时若素材库中已有相同 hash 的图片，会自动复用，提示「素材库已有相同图片，已直接复用」（不重复占用存储）
+- 上传完成后图片自动归入当前选中的文件夹（未选中时进 **未分类**）
+
+## 4. 图片操作
+
+把鼠标悬停到任一图片缩略图，会出现操作按钮：
+
+- **重命名**：仅改本地素材库里的展示名，不影响已发布到第三方平台的内容
+- **移动**：把图片移到其他文件夹
+- **删除**：
+  - 如果图片正被文章引用：提示 **图片正在使用中**，并展示哪些文章在引用
+  - 强制删除按钮：**仍然删除**（**会同步影响已绑定文章**，慎用）
+
+## 5. 引用追踪
+
+每张图片支持查看引用关系，分两类：
+
+- **正文引用**：文章正文里的配图
+- **封面引用**：作为文章封面/订阅包封面被引用
+
+> 删除被引用的图片会导致已发布文章里图片链接失效（取决于第三方平台的存储策略）。建议先确认无引用再删除。
+
+## 6. 在哪里会用到这里的图片
+
+- **文章发布弹窗 → 上传封面图 → 选择素材库**：从这里挑封面
+- **自定义生成 / 定时任务 → 封面图**：同样的素材选择器
+- **KOL 订阅包封面**（仅 KOL 角色）：精调模板包的封面图
+- **文章编辑器**：富文本中插入图片时调用
+
+## 7. 常见问题
+
+- **上传一直转圈**：检查 **存储容量** 是否已满；满额时上传会被前端拦截
+- **明明上传了图片，列表里没看到**：上传时未选中文件夹，图片会进 **未分类**；切到 **未分类** 即可看到
+- **图片删了文章里还显示**：第三方平台已发布的内容里图片不会随之消失，但本地素材库里再次发布时会失败
diff --git a/user-manual/08-数据追踪.md b/user-manual/08-数据追踪.md
new file mode 100644
index 0000000..3c9c5e3
--- /dev/null
+++ b/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 过期需要重新授权
+- **引用排行里没看到自己的文章**：归因按"发布外链主体"匹配；要确认文章已发布到第三方平台并产生了外链，且模型在采样窗口内引用了这条外链
diff --git a/user-manual/09-桌面客户端.md b/user-manual/09-桌面客户端.md
new file mode 100644
index 0000000..3f2ab06
--- /dev/null
+++ b/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 机器
diff --git a/user-manual/10-精调模板与KOL.md b/user-manual/10-精调模板与KOL.md
new file mode 100644
index 0000000..aecc113
--- /dev/null
+++ 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)
diff --git a/user-manual/11-AI点数与套餐.md b/user-manual/11-AI点数与套餐.md
new file mode 100644
index 0000000..153d980
--- /dev/null
+++ b/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 点数流水」
diff --git a/user-manual/12-常见问题.md b/user-manual/12-常见问题.md
new file mode 100644
index 0000000..872ae9f
--- /dev/null
+++ b/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）+ 控制台事件流截图（如果是发布/采集类问题）
+
+## 十、文档反馈
+
+如果在使用本手册过程中发现：
+
+- 描述与控制台实际行为不一致
+- 漏掉了某个常见操作场景
+- 截图/示意图不够清晰
+
+请直接联系本租户的省心推管理员或对接运营。控制台代码会持续迭代，文档也会同步更新。
diff --git a/user-manual/README.md b/user-manual/README.md
new file mode 100644
index 0000000..62391a8
--- /dev/null
+++ b/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)。