DocsGPT 开源二开第一步：如意知识库工厂怎么换脸？

OK，OK，大家好，欢迎大家来到大鹏 AI 教育，我是张大鹏。

前几篇我把 DocsGPT 跑通了、评测搭好了、编码坑也填了，系统在我机器上转得很欢。但上周我把仓库开源之后，直播间立刻有同学发问：你这仓库首页全是英文，大标题写着 DocsGPT，跟你书里讲的如意知识库工厂是一个东西吗？

问得好。这就是二开项目最容易被忽略的一步：换脸。系统跑通只是内功，门面不换，别人一眼看到的还是原项目，你讲得再热闹，人家也对不上号。今天就讲我是怎么给这个项目换脸的：改了哪五个文件、里面藏着一个 i18n 的小坑、以及比改代码更重要的一条纪律。

先说清楚：换脸不是洗项目

有同学一听换脸就皱眉头：把人家开源项目的名字换成自己的，这不是抄袭吗？

仓库根目录的 LICENSE 原封不动保留，arc53 的版权声明一个字没动；
上游原版 README 完整留档到 ruyi/docs/UPSTREAM_README.md，随时可查；
README 里明确写着本仓库是 DocsGPT 的中文二开，链接指回原项目。

一句话：品牌是我的，出身写清楚。这既是协议要求，也是对原作者的体面。开源世界里，站在巨人肩膀上不丢人，丢人的是踩着巨人还说没这个人。

换脸换哪里：一共五个文件

我给学员总结过，一个 Web 项目的脸由三层组成：仓库门面（README）、页面招牌（标题和主视觉）、默认语言。对应到 DocsGPT，动了五个文件。

第一层：README 整体重写

旧 README 是上游的英文介绍，和我的书完全对不上。我把它整个替换成中文门面：项目定位、快速上手、书的章节和仓库标签的对照表、评测跑分。读者从书里翻到仓库，或者从仓库摸到书，两边说的是同一套话。

第二层：页面招牌，两处小改动

浏览器标签页的标题在 frontend/index.html：

html 复制代码

- <html lang="en">
+ <html lang="zh-CN">
- <title>DocsGPT</title>
+ <title>如意知识库工厂 RuyiDocsGPT</title>

首页正中央那个大标题在 frontend/src/Hero.tsx，就一行：

tsx 复制代码

- <span className="text-4xl font-semibold">DocsGPT</span>
+ <span className="text-4xl font-semibold">如意知识库工厂</span>

改完刷新页面，学员在直播间看到的第一眼就是中文招牌。顺带交代一句：标题旁边那个 logo 图我暂时保留了，图片素材以后再换，文案先行。

第三层：默认语言，这里有个坑

DocsGPT 前端自带 i18n 多语言，中文包 zh.json 是现成的，按理说中文用户打开就该是中文界面。但实测不是，默认还是英文。问题出在 frontend/src/locale/i18n.ts，我改了两处：

ts 复制代码

- fallbackLng: 'en',
+ fallbackLng: 'zh',
+ load: 'languageOnly',

第一处好理解，兜底语言从英文换成中文。第二处才是坑的关键：中文用户浏览器报告的语言代码是 zh-CN ，而语言包注册的名字叫 zh 。i18next 默认拿着 zh-CN 去找语言包，找不到就滑向兜底的英文。加上 load: 'languageOnly'，它才会把 zh-CN 截断成 zh 去匹配，中文包这才命中。

这个坑我在直播里演示时特意留了一手：先只改 fallbackLng，刷新，界面纹丝不动还是英文，弹幕里一片问号；再加第二行，刷新，全场中文。很多国际化项目对中文用户不友好，卡的就是这种区域后缀匹配的细节。

最后是 frontend/src/locale/zh.json，把中文包里出现的品牌名 DocsGPT 全部换成如意知识库工厂，一共 14 处，改完跑了一遍 JSON 校验防手抖。

四个前端文件的改动全貌，一张图看完：

比改代码更重要的：给上游记账

五个文件改完，脸是换好了。但真正值钱的动作是下面这个。

我的仓库里有一份 ruyi/docs/UPSTREAM_SYNC.md，里面维护着一张二开改动清单：每动一个上游的文件，就登记一行，写清楚改了什么、为什么改、能不能回滚。这次换脸的四个前端文件，全部入账：

文件	改动	原因
`frontend/index.html`	title 和 lang 改中文	品牌化/中文化
`frontend/src/Hero.tsx`	主标题换如意知识库工厂	品牌化
`frontend/src/locale/i18n.ts`	fallbackLng 改 zh，加 languageOnly	默认中文
`frontend/src/locale/zh.json`	品牌名替换 14 处	品牌化

为什么这么较真？因为二开项目的命门是上游还在往前跑。DocsGPT 上游每周都有提交，将来我同步上游代码，这些被我改过的文件就是冲突高发区。有这张清单，冲突来了我一眼知道哪些是我的改动、为什么改、怎么保；没这张清单，半年后合并冲突糊你一脸，你自己都想不起来当初为什么动这一行。

二开不登记，等于借钱不打条。 这是我这个项目里最想让你带走的一句话。

诚实交代没做的事

换脸这一步我刻意控制了范围：logo 图片没换，前端构建没跑（那台机器没装前端依赖，这次改动全是文案和配置级，风险可控）。二开的节奏就是这样，每次只动一层，动完留痕，跑通再动下一层，比一口气大改到处冒烟强得多。

最后说两句

换脸是二开里技术含量最低、但回报最高的一步：README 重写一篇，前端四个文件加起来不到四十行改动，项目就从别人的 Demo 变成你自己的产品门面。但配套的两个动作不能省：协议姿势要正，上游账本要记。

这个项目整个开源在 GitHub（搜 RuyiDocsGPT），换脸的完整改动就在提交历史里，你可以一行一行对着看。配套的书《大鹏 RAG 实战：如意知识库工厂》第 9 章讲的就是这套二开方法论。下一篇聊点惊险的：我怎么用钓鱼题测我的 RAG 系统会不会瞎编。

好，今天就到这里。