wanzi/ftb-project-management

Fork 0

Files

Script Generator 0043fa9682 docs(问翻小宝): 设计静态帮助中心

2026-06-30 19:07:27 +08:00

6.2 KiB

Raw Blame History

问翻小宝第一阶段：静态帮助中心设计

背景

问翻小宝第一阶段用于解决新系统用户“不知道怎么用”的问题。它不是小宝预警的一部分，也不在第一阶段调用 AI 分析业务数据。所有答案来自内置静态帮助包，避免浪费 AI token，并保证操作说明稳定、可复查。

目标

在问翻小宝对话页中，根据用户输入关键词返回系统使用帮助。
帮助内容覆盖产品、项目、版本、需求池、调研、产品方案、AI 拆解、UI 设计、开发任务、测试用例、Bug、日志记录。
每篇帮助文章包含适用场景、入口路径、操作步骤、必填字段、状态流转、注意事项和真实页面配图。
配图通过打开本地系统页面截图生成，保存为静态图片资源。
第一阶段不调用 AI，不消耗模型 token。

非目标

不做 AI 自由问答。
不分析用户当前业务数据。
不做后台帮助文章维护。
不做移动端适配。
不让 AI 生成示意图，配图必须来自真实本地页面截图。

内容范围

第一批内置 12 篇帮助文章：

产品：新建产品、产品字段、产品作为顶层容器的作用。
项目：新建项目、项目归属产品、项目与版本/需求的关系。
版本：新建版本、必填字段、版本号、预期发布日期、成员、版本状态。
需求池：新建需求、需求字段、需求采纳、需求状态含义。
版本纳入需求：从需求池把已采纳需求关联到版本。
调研：创建调研计划、管理方向/进度、完成条件。
产品方案：创建产品方案、关联需求覆盖、提交成果链接。
AI 拆解：入口、触发条件、开发任务拆解、测试用例拆解、采纳草稿。
UI 设计：创建 UI 设计计划、管理进度、提交成果。
开发任务：新建任务、必填字段、领取与计划、开发中、自测、提测。
测试用例与 Bug：新建测试用例、开始测试、通过/失败/阻塞、从失败用例创建 Bug、Bug 状态流转。
日志记录：系统自动记录哪些行为、在哪里查看、活动记录和计划日志的区别。

帮助文章数据结构

帮助文章使用前端内置静态 TypeScript 数据：

export type HelpArticle = {
  id: string;
  title: string;
  category: string;
  keywords: string[];
  scenario: string;
  entry: string;
  steps: string[];
  requiredFields: string[];
  statusFlow: string[];
  notes: string[];
  images: HelpImage[];
  relatedIds: string[];
};

export type HelpImage = {
  src: string;
  alt: string;
  caption: string;
};

建议文件：

apps/web/lib/wenfan-help-articles.ts：文章内容。
apps/web/lib/wenfan-help-search.ts：关键词搜索和排序。
apps/web/lib/wenfan-help-search.test.ts：关键词命中测试。
public/help/wenfan-xiaobao/：帮助截图资源。

关键词触发设计

搜索只在本地执行。用户输入后按命中分数排序，返回最高分文章。

匹配信号：

标题命中：最高权重。
关键词命中：高权重。
类目命中：中高权重。
步骤、字段、注意事项命中：中权重。
相关模块命中：低权重，用于补充相关帮助。

关键词要做得厚一些，每篇文章至少包含这些类型：

模块词：产品、项目、版本、需求池、开发任务、测试用例、Bug。
动作词：新建、创建、编辑、采纳、关联、纳入、领取、开始、提测、提交、失败、通过、阻塞。
口语问法：怎么建、在哪建、怎么填、要填什么、怎么进入版本、怎么提 Bug、怎么提测。
同义词：采纳/通过，纳入/关联/加入版本，提测/提交测试，产品方案/原型/成果链接。
常见误写：bug、BUG、Bug，AI拆解、ai拆解、任务拆解。

未命中时不调用 AI，而是返回可点击的问题分类和示例问题。

对话展示设计

命中文章后，聊天区展示：

标题。
一句话适用场景。
入口路径。
操作步骤。
必填字段。
状态流转。
注意事项。
配图。
相关帮助按钮。

回复文案以“帮助文章内容”为准，不生成开放式推理答案。第一阶段可以保留静态模拟对话，但发送后应能用本地搜索结果替换回复内容。

配图设计

配图来自真实本地页面截图：

使用本地开发服务打开对应页面。
用截图脚本生成桌面尺寸截图。
保存到 public/help/wenfan-xiaobao/。
文章通过相对路径引用图片。

建议新增脚本：

apps/web/scripts/capture-wenfan-help-screenshots.mjs

脚本职责：

打开指定路由。
等待页面稳定。
截图保存。
后续可扩展为按选择器截关键区域。

第一阶段截图可以先覆盖关键页面和入口位置，不要求把每个弹窗里的每个字段都逐个截图；文章步骤里说明字段，截图负责帮助用户定位入口和页面区域。

数据流

用户输入
  -> normalizeQuery
  -> searchHelpArticles
  -> 命中文章
  -> 渲染帮助答案
  -> 展示相关帮助

没有后端调用，没有 AI 调用，没有业务数据写入。

组件划分

WenfanXiaobaoPage：页面容器、历史列表、对话区、输入框。
HelpAnswer：渲染一篇帮助文章。
HelpRelatedActions：渲染相关帮助按钮。
wenfan-help-search.ts：纯函数搜索。
wenfan-help-articles.ts：静态知识包。

验证计划

单元测试：关键词命中应返回正确文章。
单元测试：同义词和口语问法可命中对应文章。
单元测试：未命中时返回空结果或默认建议。
类型检查：pnpm --filter web type-check。
Web 检查：curl http://localhost:3000/wenfan-xiaobao 返回 200。
截图脚本：确认能生成至少一张帮助图片。

后续扩展

如果帮助内容频繁变更，再做后台可维护帮助文章。
如果静态搜索覆盖不足，再考虑接入轻量 AI 仅用于“改写已命中文章”，但不让 AI 自由分析系统数据。
如果后续需要更强搜索，可引入本地全文索引或拼音匹配。

6.2 KiB Raw Blame History Unescape Escape