页面反馈
Docsbook 中的页面反馈是一项此页面是否有帮助？控件，读者只需点击一次即可回答——无需填写表单、无需电子邮件地址，也无需帐户。投票会作为针对该页面的事件记录下来，并作为你可以据此采取行动的 Webhook。收集反馈不会调用任何模型，也不会产生任何费用。
评分是一个指示器，而不是分数。本页面既介绍如何收集一次点踩，也同样强调点踩并不能证明什么。
你将获得什么#
- 每个页面上一键评分，每个套餐均在一处或两处提供。
- 投票会立即传达到你自己的系统——一个
feedback.receivedwebhook，以及在点踩时触发的第二个chat.negative_feedbackwebhook，因此差评一发生就能发送到团队频道。 - 每位读者的互动轨迹。在访客时间线中，投票会显示为“认为页面有帮助”或“认为页面没有帮助”，与该读者执行的其他所有操作并列显示，这正是让单个投票变得可解读的地方。
- 一个已经知道如何处理反馈的队列。两个已提供的代理路由分别从负面反馈和未回答的聊天问题开始，最终生成一个页面草稿。
读者可以评价什么？#
存在三种控件，而它们衡量的内容并不相同。
| 页面下方 | “本页”面板中 | AI 回答下方 | |
|---|---|---|---|
| 评价对象 | 页面 | 页面 | 该条助手回答 |
| 位置 | 文章末尾、上一页/下一页链接上方 | 大纲中、目录下方 | 聊天面板中每条回答旁边 |
| 设置 | 评价此页面（内容选项卡） | 评价页面（右侧边栏选项卡） | AI 聊天的一部分 |
| 默认状态 | 开启 | 关闭 | 随聊天功能启用 |
| 在手机上 | 内嵌显示 | 位于浮动大纲按钮后方，以底部抽屉形式显示 | 显示 |
| 写入的事件 | docs.page_feedback_up / _down |
相同 | docs.ai_like / docs.ai_dislike |
页面下方的评价栏是大多数项目希望启用的功能。读者在读完页面后会看到它，而此时正是他们形成看法的时刻；大纲控件只有在读者的视线已经落在右侧栏时才会被看到。这两个页面控件会写入同一个系列——它们只是提供了两个提问位置，而不是两个指标。
AI 回答的点赞/点踩属于真正不同的系列，并携带不同的字段：对话 ID 以及获得投票的问题，因为只有路径的评价只是一个无人能够据此采取行动的计数器。回答溢出菜单中的报告问题也会写入相同的踩事件。
每个控件、每次页面浏览只能投一票。投票后按钮会锁定，并由简短的感谢语替代问题。此限制针对每个控件分别生效，因此同时启用两个页面控件的项目可以从同一读者对同一页面获得两票——这是有意接受的结果：有意投两次票的读者是在两次告诉你同一件事，而跨界面去重需要共享状态，却不会带来任何额外信息价值。
开启页面反馈#
在页面下方（默认开启）：
- 登录后打开文档站点。
- 打开 Float Widget → 设置 → 内容选项卡。
- 开启为此页面评分。
在“此页面上”面板中：
- 打开 Float Widget → 设置 → 右侧边栏选项卡。
- 开启为页面评分。
也可以通过带有 update_ui_settings（show_content_feedback、show_page_feedback）的 MCP 客户端设置这两项。
每次投票会存储什么#
页面投票经过有意精简。两个页面控件都没有自由文本框、会话 ID，也不会记录读者输入的任何内容：
| 去向 | 包含内容 |
|---|---|
| 分析事件 | 事件名称（docs.page_feedback_up 或 _down）、您的项目、页面路径、读者的 IP 和国家/地区。方向编码在事件名称中，因为分析数据集的架构会直接拒绝未知的 vote 字段 |
feedback.received webhook |
page_path、vote（up/down）、comment（这些控件始终为 null）、country — 以及一个访客 ID |
chat.negative_feedback webhook，仅限反对票 |
session_id、page_path、type（thumbs_down）、comment |
| 访客身份 | 以您的项目为范围、对读者 IP 进行加盐 SHA-256 哈希后截取的 16 个十六进制字符。这与您其他分析数据使用的哈希相同，因此可以将投票与该读者的其他事件关联起来 — 而且无法还原为地址 |
有两种行为值得了解，因为它们会改变您对数据的解读：
- 您自己团队的投票会从分析数据中排除，但仍会发送到您的 webhook。写入分析数据时会跳过内部流量，因为您测试自己的页面并不代表读者信号 — 但所有者仍应获知发生了评分。
comment字段存在于负载中，但这些控件永远不会填充它。它是为会收集该字段的界面预留的；目前两个页面控件都不会收集。
AI 答案投票会存储其项目、读者所在的页面、会话 ID 和问题 — 不包含答案文本，也不会记录超出相同 IP 哈希之外的读者身份信息。
所有者看到的内容#
| 界面 | 显示内容 | 计划 |
|---|---|---|
| 分析 → 反馈选项卡 | 总计和按页面统计的赞和踩，前 20 行按踩优先排序——被踩的页面是需要修复的页面，被赞的页面只能确认现有功能正常 | 所有计划 |
| 信息流 / 访客时间线 | 每次投票都会作为读者轨迹中的独立事件显示，并标记为成功或问题 | 所有计划 |
feedback.received 和 chat.negative_feedback Webhook |
投票发生时立即将其发送到你的 URL——经过签名并支持重试，不同于聊天钩子 | 所有计划 |
get_negative_feedback（MCP） |
按踩的数量对页面进行排名 | 专业版 |
get_ai_unanswered（MCP） |
未生成答案的聊天问题——同一信号的另一半 | 专业版 |
所有计划都可以注册 Webhook；MCP 路径和 REST 路径都会检查相同的功能权限，只有三个高级事件（流量激增、流量下降、调用 MCP 工具）被单独区分出来。多个 MCP 工具描述仍将这两个事件标记为专业版——该文本已经过时，并不反映实际行为。
有疑问时——请将“反馈”选项卡理解为 AI 答案系列，而不是页面系列。该选项卡的总计和按页面显示的行来自对
docs.ai_like/docs.ai_dislike的查询，即由 AI 答案点赞所写入的事件。页面控件会写入docs.page_feedback_up/_down，而该选项卡背后的查询不会读取这些内容。因此，今天的页面投票会到达你的 Webhook 和访客时间线，但不会计入“反馈”选项卡的统计数据。get_negative_feedback的情况也相同：其中自己的代码注释明确指出，页面级事件“不会在此处合并”。在此问题修复之前，请将“反馈”选项卡视为对助手答案的衡量，并使用事件信息流或 Webhook 获取页面投票。
从一个差评到你撰写的下一页#
评分不是发现本身。让它变得可执行的是评分旁边的信息：没有返回结果的搜索、助手无法回答的问题，以及读者投票后的行为。
两个代理流程已经预先接入了这套顺序，并且都适用于 Pro：
根据用户反馈改进文档 — 建议每周运行一次。它会读取读者标记为不佳的页面，然后在重复修改之前，先读取之前对这些页面进行的修复已经产生了什么效果，接着询问读者当时想完成什么任务，最后才进行编辑。加入变更历史这一步，是因为没有这一步的版本会在重写页面几秒后测量页面的健康状况，而这个数字还不可能发生变化。
根据助手对话填补空白 — 建议在 chat.no_answer 事件上运行。它会读取助手无法回答的问题，区分文档空白和糟糕的问题，选出今天值得撰写的那一个，并起草该页面。
面板中每个改进按钮背后的提示词都遵循相同的四条规则，这些规则也适用于手动操作：将每个数字与某个对象进行比较，并说明比较对象；引用你实际读取过的页面和事件；无法读取的指标应视为缺失，而不是零；在进行任何编辑之前，先停留在诊断阶段。
收集评分不会调用模型，也不会计量用量。上述代理流程属于模型工作，会消耗项目余额 — 请参阅定价页面。
为什么这是正确的方法（证据）#
| 规则 | 为什么有效 | 来源 |
|---|---|---|
| 将评分视为指示，而绝不是页面的分数 | 自愿评价系统存在两种自我选择偏差——获取偏差和低报偏差；在低报偏差中，“评分极端（无论正面还是负面）的消费者，比对产品评价中等的消费者更有可能撰写评论”——这两种偏差共同“使平均评分成为产品质量的有偏估计量” | Hu、Pavlou 和 Zhang，2017 — 在线产品评论中的自我选择偏差，MIS Quarterly 41(2) |
| 假设几乎没有人会投票，不要将沉默解读为认可 | 在四个长期运行的在线社区中，对 63,990 名参与者和 578,349 条帖子进行观察后发现，“发过一条或多条帖子的参与者不到 25%”，而排名前 1% 的参与者贡献了 74.7% 的内容 | van Mierlo，2014 — 四个数字健康社交网络中的 1% 规则，JMIR（同行评审的观察性研究） |
| 不要仅凭较低的投票数就断定页面不好 | “无应答可能会、但不一定会在调查估计中引发无应答偏差”，并且“没有任何一个最低响应率，低于该响应率时调查估计就必然存在偏差”——响应率本身并不是问题 | Groves，2006 — 住户调查中的无应答率与无应答偏差，Public Opinion Quarterly 70(5) |
| 在采取行动前，将每个评分与其周围的行为结合起来考量 | 偏差“取决于调查变量与被测量倾向之间的相关程度”——因此问题不在于有多少人投票，而在于投票的读者是否在你所测量的方面存在差异。感到困惑的读者和感到满意的读者，按下按钮的频率并不相同 | Groves，2006 — 同一篇论文 |
实际解读这四行内容时：一个有十个倒赞的页面值得打开；一个有三个赞的页面不能证明它有效；而一个完全没有投票的页面，只能说明你对它一无所知，而不是没有人不喜欢它。
限制#
- 反馈选项卡目前不会统计页面投票。 请参阅上方的问题下方区块。这是本页中之前版本文档唯一写错的一项说明，因此这里明确写出，而不是悄悄删掉。
- 投票不包含原因。 两个页面控件都不会收集自由文本，因此点踩只能告诉你出了问题，却永远不会告诉你具体是什么问题。AI 答案的差评之所以包含更多信息，只是因为其中带有问题内容。
- 评分按查看次数计算，而不是按读者计算。 明天再次访问的读者可以再次投票；如果一个项目同时启用了两个页面控件，那么同一位读者在查看一个页面时可以投两票。
- 反馈在教学类页面上最有价值——例如教程和操作指南，因为读者要么完成了任务，要么没有完成。在参数表上，评分几乎无法告诉你任何信息。
- 我们没有发布 Docsbook 反馈率应达到多少的基准。 尚未测量跨客户的分布情况，因此没有可供你比较的“健康”数值。上面的外部来源讨论的是一般情况下的自愿反馈，而不是 Docsbook 站点。
- 负载中包含评论字段，但没有任何内容会填入其中。 如果你构建了一个能够收集评论的界面，webhook 契约中已经为此预留了位置；默认情况下，该字段始终为
null。