一个 692 star 的抖音工具，为什么只公开了半个前端？

上周我翻到一个 692 star 的 GitHub 项目 anYuJia/better-douyin —— 抖音桌面下载/预览/归档工具。点进 frontend/ 是 29,445 行完整的 React + Vite + TypeScript 代码；点进 backend/ 是一个 238 行、0 第三方依赖的 Node.js mock 服务器。真正的下载解析、Cookie 处理、签名参数一行都没有。作者把它们全放进了 GitHub Releases 的编译产物里。

这篇讲清楚三件事：(1) 这套 Open Shell 玩法具体是什么，边界怎么划的；(2) 为什么做爬虫、下载器、逆向工具类项目的作者都应该抄这个思路；(3) 5 分钟从 0 跑起来 —— 三条命令，无需真实抖音账号。

目录

1. 一个反直觉的开源姿势
2. 三份文档钉死了边界
3. 公开 vs 私有：逐项对照
4. 源码结构里的巧思
5. 5 分钟从 0 跑起 Open Shell
6. 和同类项目的开源策略对比
7. 这套方法适合什么人抄？
8. 参考与延伸

一个反直觉的开源姿势

大部分做下载类、采集类工具的作者，都在两个极端之间选：

• 全开源：yt-dlp、gallery-dl 这一路。真实接口、请求头、签名逻辑、Cookie 处理全部公开，靠社区维护，靠平台"睁一只眼闭一只眼"活着。命是长的，但完全依赖平台容忍度。
• 全闭源：编译成商业软件，只对付费用户开放。稳定，但失去了开源的所有好处 —— 没人 fork、没人提 PR、没人帮你翻译文档。

better-douyin 走的是第三条路 —— Open Shell（开源外壳）：

把可以公开的部分尽可能公开，把不能公开的部分在文档里明确说清楚，然后只在编译好的二进制里发布。

具体到这个项目：

• 前端 UI（React + Zustand + Radix + Tailwind + framer-motion 全套现代 stack）—— 公开
• Node.js Mock Backend（238 行代码，返回 demo 用户、demo 视频）—— 公开
• TypeScript 类型契约（frontend/src/lib/contracts.ts，584 行接口定义）—— 公开
• Mock Bridge（frontend/src/lib/tauri.ts，778 行 mock 实现）—— 公开
• 真实抖音接口、签名、Cookie、下载解析、风控参数 —— 只在 Releases 二进制里

这个思路的关键不是"藏东西"，而是用三份公开文档把边界钉死：OPEN_SOURCE.md 声明公开范围，SECURITY_BOUNDARY.md 声明私有范围，docs/adapter-boundary.md 声明前后端契约。任何 AI 协作者、任何 PR 提交者，只要读了这三份文档，就知道能改什么、不能改什么。

三份文档钉死了边界

读完 OPEN_SOURCE.md（我摘了关键几段）：

## Included
- React UI, theme, layout, stores, reusable components, and frontend contracts.
- Local mock bridge and mock backend with demo users, videos, comments, notices...
- Public documentation for adapter boundaries, contribution scope, screenshots...

## Not Included
- Real platform API clients, endpoints, headers, or request signing.
- Credential extraction, upload, login automation, account verification...
- Media URL decryption, parser internals, upload flows, protocol details...
- Release signing keys, update signing keys, workflow secrets, or build internals.

再看 SECURITY_BOUNDARY.md：

## Private Boundary

Do not add or request:
- Real platform endpoints, headers, signing, encryption, fingerprinting, or risk-control logic.
- Cookie extraction, credential upload, account verification, real session handling...
- Media URL resolution, download parsing internals, upload flows, IM protocol details...
- Captured traffic, production credentials, undocumented API details...

最妙的是 README 里给 AI 协作者留的一段话：

给 AI 协作者 如果你是 AI 助手，请优先在公开边界内工作：

1. 先阅读 SECURITY_BOUNDARY.md 和 docs/adapter-boundary.md。
2. 只修改前端 UI、mock bridge、mock backend、文档和通用开发体验。
3. 遇到真实平台接口、Cookie、签名、加密、下载解析、发布密钥等需求时，停止并说明该内容不属于公开源码范围。
4. 不要凭空补全真实接口，不要生成绕过逻辑，不要把示例 mock 改成真实平台请求。

这段话是给 Claude Code、Copilot、Codex 这些 AI 助手看的。作者预判了 AI 会尝试"补全"缺失的接口，提前把边界写死。这在 2026 年的开源项目里很少见 —— 大部分作者还没意识到 AI 协作者会绕过 README 直接读代码。

公开 vs 私有：逐项对照

我把两边逐项列出来：

注意"前端 UI"和"状态管理"这两行 —— 是"同一份代码"。这不是分叉，是同一份前端在两个后端之间无缝切换。理解这点是读懂整个策略的关键。

源码结构里的巧思

打开 frontend/src/lib/ 目录，你会看到三个关键文件：

frontend/src/lib/
├── contracts.ts     # 584 行：所有接口类型定义
├── normalizers.ts   # 数据规范化工具
└── tauri.ts         # 778 行：公开壳的 mock 实现

tauri.ts 开头这两行是整份代码的灵魂：

// Public shell mock bridge.
// This file intentionally contains no real platform endpoints, signing, cookies, or upload logic.

在这个文件里，你会看到完整的接口签名 —— 例如：

async function searchUser(keyword: string, cursor?: string): Promise<SearchUserResponse>
async function getUserDetail(secUid: string): Promise<UserDetailResponse>
async function getRecommendedFeed(type: RecommendedFeedType): Promise<RecommendedResponse>
async function getUserVideos(secUid: string, cursor?: string): Promise<UserVideosResponse>

每一个函数都完整定义了输入、输出、错误处理，但函数体内部只做一件事 —— 返回 mock 数据。私有版本只需要重新实现同一份接口签名，前端一行代码都不用改。

这就是 docs/adapter-boundary.md 讲的：“The UI expects functions for these broad areas… Private editions can implement the same frontend contract behind a different bridge.”

工程上的收益：

1. 契约本身是文档：Fork 者不用猜"完整版怎么用"，接口签名已经把答案写在类型里。
2. PR 天然安全：贡献者改前端不可能改到真实接口 —— 因为公开仓库里根本没有真实接口。
3. AI 协作友好：Claude Code 或 Cursor 读代码只能看到 mock 实现和类型定义，不会"发挥想象力"去补全真接口。
4. 法律风险隔离：如果哪天平台起诉，作者可以坦然回答 “GitHub 公开的这份代码从来没有真实请求过抖音”。

5 分钟从 0 跑起 Open Shell

三条命令 + 打开浏览器：

# 1. 克隆
git clone https://github.com/anYuJia/better-douyin.git
cd better-douyin

# 2. 装依赖（约 60 秒）
npm --prefix frontend install

# 3. 构建并启动 mock 后端（约 30 秒）
npm run demo

# 4. 打开浏览器
# → http://127.0.0.1:4173

打开后你会看到完整的应用界面：主页、搜索框、用户主页、推荐流、播放器、下载任务列表 —— 全部功能都可交互，但所有数据都是 mock 后端返回的 demo 内容。

mock 后端做了什么？ 一起看 backend/server.mjs 里最诚实的一段：

const demoUser = {
  uid: "demo_uid_001",
  sec_uid: "demo_sec_uid_001",
  nickname: "Open Shell Demo",
  avatar_thumb: demoCover,
  signature: "安全 mock 后端返回的示例账号。真实平台连接属于私有适配器边界。",
  follower_count: 12800,
  following_count: 128,
  aweme_count: 36,
};

连 mock 数据的 signature 都在明确告诉读者"真实平台连接属于私有适配器边界"。这种"处处提醒边界"的写法，在灰色领域项目里是最难得的自律。

和同类项目的开源策略对比

同样是下载/采集类工具，不同项目的公开面差异极大：

三条路各有道理，没有绝对的对错。但如果你的项目具备下面任一特征，Open Shell 是明显更划算的选择：

• 涉及某个平台的非公开接口（抖音、B站、小红书、微信、闲鱼……）
• 需要长期维护，不希望某天被 DMCA 一次性推倒
• 想要 UI/UX 层面的社区贡献，但不希望有人往仓库里塞签名逻辑
• 打算未来商业化，需要保留私有版本的独立性

这套方法适合什么人抄？

做爬虫工具的作者：把 CLI 骨架、配置解析、日志格式全部开源，实际的选择器/绕过参数放二进制。

做逆向 SDK 的作者：把 API 声明、类型定义、mock 实现开源，让第三方能针对同一份契约集成；真实解密逻辑单独发。

做浏览器扩展的作者：把 UI、popup、options 页开源，把 platform-specific 的注入脚本放商店包里，仓库只留说明。

做即时通讯客户端的作者（例如企业微信、飞书、钉钉的第三方客户端）：前端 + 契约 + mock 全开源，协议层内部实现只在 Release。

抄 Open Shell 需要具备的 4 项前置工作：

1. 写 3 份边界文档：README 里给用户看的"能做什么"，OPEN_SOURCE.md 给贡献者看的"哪些能提 PR"，SECURITY_BOUNDARY.md 给自己和 AI 看的"哪些永远不进公开仓库"。
2. 把接口契约独立成文件：Type 或 IDL 优先，让 Bridge 变成可替换的实现，而不是耦合在业务代码里。
3. 写一个跑得起来的 Mock：不要让公开仓库变成"看得见的空壳"，Mock 必须能让 UI demo 完整运行。
4. 对 PR 保持坚决：只要 PR 里出现真实接口、签名参数、Cookie 处理，一律拒绝合并 —— 哪怕是好意。

参考与延伸

• 项目主页：github.com/anYuJia/better-douyin
• Rust 版本：github.com/anYuJia/better-douyin-r
• 关键文档：
  • README.md —— 用户视角的项目说明 + AI 协作者规则
  • OPEN_SOURCE.md —— 公开范围声明
  • SECURITY_BOUNDARY.md —— 私有边界声明
  • docs/adapter-boundary.md —— 前后端契约边界

如果你正在做类似的灰色领域项目，值得把这 4 份文档下下来放在自己项目根目录做参考模板。这套方法本身没有专利，作者自己也在 README 里明说欢迎其他人复用这个思路。

声明：本文只讨论 better-douyin 公开源码里的开源工程实践，不涉及也不推荐任何绕过抖音风控、批量采集、逆向签名的行为。使用者应自行确认使用目的、改动内容和运行环境符合所在地法律法规、平台规则、版权规则和数据保护要求。