From 0043fa9682ab8c7a2866c071990b0ab05ed24902 Mon Sep 17 00:00:00 2001
From: Script Generator <dev@scriptgen.local>
Date: Tue, 30 Jun 2026 19:07:27 +0800
Subject: [PATCH] =?UTF-8?q?docs(=E9=97=AE=E7=BF=BB=E5=B0=8F=E5=AE=9D):=20?=
 =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E9=9D=99=E6=80=81=E5=B8=AE=E5=8A=A9=E4=B8=AD?=
 =?UTF-8?q?=E5=BF=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...06-30-wenfan-xiaobao-help-center-design.md | 168 ++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-30-wenfan-xiaobao-help-center-design.md

diff --git a/docs/superpowers/specs/2026-06-30-wenfan-xiaobao-help-center-design.md b/docs/superpowers/specs/2026-06-30-wenfan-xiaobao-help-center-design.md
new file mode 100644
index 0000000..01571d3
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-30-wenfan-xiaobao-help-center-design.md
@@ -0,0 +1,168 @@
+# 问翻小宝第一阶段：静态帮助中心设计
+
+## 背景
+
+问翻小宝第一阶段用于解决新系统用户“不知道怎么用”的问题。它不是小宝预警的一部分，也不在第一阶段调用 AI 分析业务数据。所有答案来自内置静态帮助包，避免浪费 AI token，并保证操作说明稳定、可复查。
+
+## 目标
+
+- 在问翻小宝对话页中，根据用户输入关键词返回系统使用帮助。
+- 帮助内容覆盖产品、项目、版本、需求池、调研、产品方案、AI 拆解、UI 设计、开发任务、测试用例、Bug、日志记录。
+- 每篇帮助文章包含适用场景、入口路径、操作步骤、必填字段、状态流转、注意事项和真实页面配图。
+- 配图通过打开本地系统页面截图生成，保存为静态图片资源。
+- 第一阶段不调用 AI，不消耗模型 token。
+
+## 非目标
+
+- 不做 AI 自由问答。
+- 不分析用户当前业务数据。
+- 不做后台帮助文章维护。
+- 不做移动端适配。
+- 不让 AI 生成示意图，配图必须来自真实本地页面截图。
+
+## 内容范围
+
+第一批内置 12 篇帮助文章：
+
+1. 产品：新建产品、产品字段、产品作为顶层容器的作用。
+2. 项目：新建项目、项目归属产品、项目与版本/需求的关系。
+3. 版本：新建版本、必填字段、版本号、预期发布日期、成员、版本状态。
+4. 需求池：新建需求、需求字段、需求采纳、需求状态含义。
+5. 版本纳入需求：从需求池把已采纳需求关联到版本。
+6. 调研：创建调研计划、管理方向/进度、完成条件。
+7. 产品方案：创建产品方案、关联需求覆盖、提交成果链接。
+8. AI 拆解：入口、触发条件、开发任务拆解、测试用例拆解、采纳草稿。
+9. UI 设计：创建 UI 设计计划、管理进度、提交成果。
+10. 开发任务：新建任务、必填字段、领取与计划、开发中、自测、提测。
+11. 测试用例与 Bug：新建测试用例、开始测试、通过/失败/阻塞、从失败用例创建 Bug、Bug 状态流转。
+12. 日志记录：系统自动记录哪些行为、在哪里查看、活动记录和计划日志的区别。
+
+## 帮助文章数据结构
+
+帮助文章使用前端内置静态 TypeScript 数据：
+
+```ts
+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，而是返回可点击的问题分类和示例问题。
+
+## 对话展示设计
+
+命中文章后，聊天区展示：
+
+1. 标题。
+2. 一句话适用场景。
+3. 入口路径。
+4. 操作步骤。
+5. 必填字段。
+6. 状态流转。
+7. 注意事项。
+8. 配图。
+9. 相关帮助按钮。
+
+回复文案以“帮助文章内容”为准，不生成开放式推理答案。第一阶段可以保留静态模拟对话，但发送后应能用本地搜索结果替换回复内容。
+
+## 配图设计
+
+配图来自真实本地页面截图：
+
+- 使用本地开发服务打开对应页面。
+- 用截图脚本生成桌面尺寸截图。
+- 保存到 `public/help/wenfan-xiaobao/`。
+- 文章通过相对路径引用图片。
+
+建议新增脚本：
+
+- `apps/web/scripts/capture-wenfan-help-screenshots.mjs`
+
+脚本职责：
+
+- 打开指定路由。
+- 等待页面稳定。
+- 截图保存。
+- 后续可扩展为按选择器截关键区域。
+
+第一阶段截图可以先覆盖关键页面和入口位置，不要求把每个弹窗里的每个字段都逐个截图；文章步骤里说明字段，截图负责帮助用户定位入口和页面区域。
+
+## 数据流
+
+```text
+用户输入
+  -> 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 自由分析系统数据。
+- 如果后续需要更强搜索，可引入本地全文索引或拼音匹配。