OK，OK，大家好，欢迎大家来到大鹏 AI 教育，我是张大鹏。
前几篇我把 DocsGPT 跑通了、评测搭好了、编码坑也填了，系统在我机器上转得很欢。但上周我把仓库开源之后，直播间立刻有同学发问：你这仓库首页全是英文，大标题写着 DocsGPT，跟你书里讲的如意知识库工厂是一个东西吗？
问得好。这就是二开项目最容易被忽略的一步：换脸。系统跑通只是内功，门面不换，别人一眼看到的还是原项目，你讲得再热闹，人家也对不上号。今天就讲我是怎么给这个项目换脸的：改了哪五个文件、里面藏着一个 i18n 的小坑、以及比改代码更重要的一条纪律。
先说清楚：换脸不是洗项目
有同学一听换脸就皱眉头：把人家开源项目的名字换成自己的，这不是抄袭吗？
不是，前提是你姿势要正。DocsGPT 是MIT 协议，明文允许修改、分发甚至商用，只要求保留版权声明。所以我的做法是：
- 仓库根目录的
LICENSE原封不动保留，arc53 的版权声明一个字没动； - 上游原版 README 完整留档到
ruyi/docs/UPSTREAM_README.md，随时可查； - README 里明确写着本仓库是 DocsGPT 的中文二开，链接指回原项目。
一句话：品牌是我的，出身写清楚。这既是协议要求，也是对原作者的体面。开源世界里，站在巨人肩膀上不丢人，丢人的是踩着巨人还说没这个人。
换脸换哪里：一共五个文件
我给学员总结过，一个 Web 项目的脸由三层组成：仓库门面（README）、页面招牌（标题和主视觉）、默认语言。对应到 DocsGPT，动了五个文件。
第一层：README 整体重写
旧 README 是上游的英文介绍，和我的书完全对不上。我把它整个替换成中文门面：项目定位、快速上手、书的章节和仓库标签的对照表、评测跑分。读者从书里翻到仓库，或者从仓库摸到书，两边说的是同一套话。
第二层：页面招牌，两处小改动
浏览器标签页的标题在frontend/index.html：
-<htmllang="en">+<htmllang="zh-CN">-<title>DocsGPT</title>+<title>如意知识库工厂 RuyiDocsGPT</title>首页正中央那个大标题在frontend/src/Hero.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，我改了两处：
-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 系统会不会瞎编。
好，今天就到这里。
