OKOK大家好欢迎大家来到大鹏 AI 教育我是张大鹏。前几篇我把 DocsGPT 跑通了、评测搭好了、编码坑也填了系统在我机器上转得很欢。但上周我把仓库开源之后直播间立刻有同学发问你这仓库首页全是英文大标题写着 DocsGPT跟你书里讲的如意知识库工厂是一个东西吗问得好。这就是二开项目最容易被忽略的一步换脸。系统跑通只是内功门面不换别人一眼看到的还是原项目你讲得再热闹人家也对不上号。今天就讲我是怎么给这个项目换脸的改了哪五个文件、里面藏着一个 i18n 的小坑、以及比改代码更重要的一条纪律。先说清楚换脸不是洗项目有同学一听换脸就皱眉头把人家开源项目的名字换成自己的这不是抄袭吗不是前提是你姿势要正。DocsGPT 是MIT 协议明文允许修改、分发甚至商用只要求保留版权声明。所以我的做法是仓库根目录的LICENSE原封不动保留arc53 的版权声明一个字没动上游原版 README 完整留档到ruyi/docs/UPSTREAM_README.md随时可查README 里明确写着本仓库是 DocsGPT 的中文二开链接指回原项目。一句话品牌是我的出身写清楚。这既是协议要求也是对原作者的体面。开源世界里站在巨人肩膀上不丢人丢人的是踩着巨人还说没这个人。换脸换哪里一共五个文件我给学员总结过一个 Web 项目的脸由三层组成仓库门面README、页面招牌标题和主视觉、默认语言。对应到 DocsGPT动了五个文件。第一层README 整体重写旧 README 是上游的英文介绍和我的书完全对不上。我把它整个替换成中文门面项目定位、快速上手、书的章节和仓库标签的对照表、评测跑分。读者从书里翻到仓库或者从仓库摸到书两边说的是同一套话。第二层页面招牌两处小改动浏览器标签页的标题在frontend/index.html-htmllangenhtmllangzh-CN-titleDocsGPT/titletitle如意知识库工厂 RuyiDocsGPT/title首页正中央那个大标题在frontend/src/Hero.tsx就一行- span classNametext-4xl font-semiboldDocsGPT/span span classNametext-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.htmltitle 和 lang 改中文品牌化/中文化frontend/src/Hero.tsx主标题换如意知识库工厂品牌化frontend/src/locale/i18n.tsfallbackLng 改 zh加 languageOnly默认中文frontend/src/locale/zh.json品牌名替换 14 处品牌化为什么这么较真因为二开项目的命门是上游还在往前跑。DocsGPT 上游每周都有提交将来我同步上游代码这些被我改过的文件就是冲突高发区。有这张清单冲突来了我一眼知道哪些是我的改动、为什么改、怎么保没这张清单半年后合并冲突糊你一脸你自己都想不起来当初为什么动这一行。二开不登记等于借钱不打条。这是我这个项目里最想让你带走的一句话。诚实交代没做的事换脸这一步我刻意控制了范围logo 图片没换前端构建没跑那台机器没装前端依赖这次改动全是文案和配置级风险可控。二开的节奏就是这样每次只动一层动完留痕跑通再动下一层比一口气大改到处冒烟强得多。最后说两句换脸是二开里技术含量最低、但回报最高的一步README 重写一篇前端四个文件加起来不到四十行改动项目就从别人的 Demo 变成你自己的产品门面。但配套的两个动作不能省协议姿势要正上游账本要记。这个项目整个开源在 GitHub搜 RuyiDocsGPT换脸的完整改动就在提交历史里你可以一行一行对着看。配套的书《大鹏 RAG 实战如意知识库工厂》第 9 章讲的就是这套二开方法论。下一篇聊点惊险的我怎么用钓鱼题测我的 RAG 系统会不会瞎编。好今天就到这里。