Bangumi32 React Native 仓库的 Token 预算Context Budget实战指南Agent 与 LLM 如何高效读取大型静态数据项目【免费下载链接】Bangumi:electron: An unofficial https://bgm.tv ui first app client for Android and iOS, built with React Native. 一个无广告、以爱好为驱动、不以盈利为目的、专门做 ACG 的类似豆瓣的追番记录bgm.tv 第三方客户端。为移动端重新设计内置大量加强的网页端难以实现的功能且提供了相当的自定义选项。 目前已适配 iOS / Android。项目地址: https://gitcode.com/GitHub_Trending/ba/Bangumi导读本指南基于 Bangumi项目内部代号 Bangumi32仓库中的 .claude/skills/context-budget.md 及其姊妹文档 .claude/docs/token-budget.md系统讲解在承载大量静态 JSON 数据与二进制资源的 React Native 项目中AI 编码 Agent、LLM 与人类开发者应如何制定并执行 Token 预算规则以在有限上下文窗口内完成高质量代码阅读、定位与修改。读完本文你将掌握一套路径黑名单 替代读取策略 数据结构推理工作流的上下文管理方法论并看到它在 Bangumi 仓库源码loadJSON/getJSON数据层、AC 自动机搜索模块中的真实落地方式。一、背景为什么一个 App 仓库需要Token 预算规则Bangumi32 是一个基于 React Native Expo SDK 54 的 bgm.tvBangumi 追番社区第三方客户端代码规模庞大src/下包含 80 可复用组件、100 页面模块、18 个 MobX domain store、35 工具模块见 .claude/docs/architecture.md。支撑这些页面的是大量随包携带的静态数据——这正是 Token 开销的主要来源。对仓库做实际测量可以直观理解文档的顾虑目录实测体积du -sh内容src/assets/约 19M文档标注 39M以仓库实际为准图片、字体、图标、JSONsrc/assets/fonts/约 9.2M多套中文字体TTFsrc/assets/json/约 5.1M全部 JSON 数据文件src/assets/images/约 2.2M各模块配图src/assets/iconfont/约 128K图标字体与生成脚本其中单个 JSON 文件体积相当可观超过 50KB 阈值的文件在src/assets/json/下比比皆是mono.json约 393KBkatakana.json约 348KBvib.json约 285KBnsfw_id_distribution.json约 104KBuser.json约 56KBsubstrings/下的anime.json、book.json、game.json、real.json、alias.json以及thirdParty/下的各.min.json、typerank/下的各*-ids.json均超过 50KB对 LLM 而言一个 393KB 的 JSON 文件按 token 折算可能占用数万乃至十几万 token——相当于一次性烧掉一个大模型的上下文窗口。这正是文档第一条规则NEVER read these paths存在的根本原因。二、核心规则禁止读取的路径清单.claude/skills/context-budget.md 用NEVER级别的措辞定义了一组路径黑名单适用场景是任何需要阅读仓库内容的 Agent 会话Codex / Claude Code / Cursor 等禁止读取的路径内容说明原因src/assets/json/全部 JSON 数据mono.json、vib.json、substrings/*、typerank/*、thirdParty/*单文件可达数百 KB总 5.1Msrc/assets/图片、字体等二进制资源文档标注 39M二进制无法被文本模型有效消费且体积巨大dist/构建输出目录由源码生成无信息增量node_modules/第三方依赖体积以百 MB 计且可随时通过 lockfile 推断metro-cache/Metro 打包缓存机器生成无阅读价值web/test/*.json测试夹具数据仅服务于网页端测试任何超过 50KB 的.json文件全仓库范围单个文件即可能耗尽上下文这套规则的潜在设定是项目本身是只读研究对象的Agent 的工作是理解、定位与修改src/下的 TypeScript 代码而不是消费这些巨型数据文件。三、替代方案不读数据文件应该优先读什么文档在给出黑名单的同时明确列出CAN do instead的替代读取策略保证 Agent 在绕开大文件后依然具备完整的代码理解能力自由读取src/下的源码——components、stores、utils、screens 等目录全部开放。这些是 TypeScript 文本体积可控、信息密度高。读取配置文件——package.json、tsconfig.json、app.json、eas.json。一份配置往往能回答技术栈、路径别名、构建配置、依赖版本等高频问题。用 grep/find 定位引用——当需要知道某个 JSON key 或资源在哪里被使用时直接全文搜索而不是打开数据文件本身。读 import 语句推断数据结构——数据文件再大它的消费方import/require只有寥寥几行从消费方的使用方式即可反推数据的形状。万不得已才读数据文件且只用limit参数读前 20 行——了解结构即可不必读完。这套替代方案的背后逻辑是理解一个数据的契约类型、结构、消费方式几乎永远比理解它的内容具体数值更重要——除非你正在 debug 某个具体数据值而那种场景往往也可以靠 grep 精确命中单行解决。四、数据理解方法论不读文件也能掌握数据结构的四步工作流文档给出了一个明确的四步推理流程用于在没有读取数据文件的情况下理解数据。以 Bangumi 的 JSON 数据层为例每一步都能在源码中找到精确落点。第 1 步找到 TypeScript 类型定义JSON 数据的所有形状都被集中声明在 src/assets/json/types.ts 中。该文件定义了JSONPath联合类型以模板字符串精确枚举所有可用路径如substrings/${anime|book|game|real|alias|addon}、typerank/${SubjectType}以及katakana、group、mono、nsfw_id_distribution、thirdParty/ja.min、thirdParty/wenku.min等字面量——这意味着文件名本身就被类型系统约束死了读类型定义就等于看到了数据目录的全景。各数据的具体结构如JSONMono { i: number; n: string; c: string; r: number; p?: 1 }[]一眼可知mono.json是条目人物的数组包含 id、名称、封面等字段JSONGroup是带t/n/i字段的数组JSONWenku则完整描述了文库条目索引的所有字段。JSONData映射类型用Expand...将路径与结构一一对应构成loadJSON/getJSON的完整类型签名。第 2 步找到 import/require 语句看它如何被消费核心消费入口是 src/assets/json/index.ts客户端与 src/assets/json/index.web.ts网页端。两端暴露相同的 API但底层实现完全不同客户端index.ts通过switch (name)配合require(./substrings/anime.json)等语句做静态打包命中后写入memoMap 缓存并带有兜底try/catch与defaultValue参数保证失败时静默返回空对象。网页端index.web.ts改为fetch(/assets/json/${name}.json)运行时拉取且对部署在 GitHub Pages 的场景自动拼接Bangumi-Storybook/storybook-static前缀——注释点明设计意图客户端与本地获取方式是一致的目的是网页端能把 json 文件从打包中剔除。也就是说同样的 API 在移动端走require打包进 bundle在网页端走 HTTP 按需加载这是通过双入口index.ts/index.web.ts由 Metro 的 resolver 平台分支实现的。公开 API 为两个函数loadJSONT extends JSONPath(name, defaultValue)异步加载带memo缓存getJSONT extends JSONPath(name, defaultValue, autoLoad)同步读取仅从memo取值autoLoad为true时若未加载会通过setTimeout延迟发起loadJSON用下一次访问命中的方式避免阻塞当前渲染。例如 src/utils/app/data-source.ts 中的getJSON(nsfw_id_distribution, [], true)就利用了 autoLoad 预热机制。第 3 步读处理数据的 store 或 utility数据最终在业务逻辑中被加工。以同人志/NSFW/文库模块为例消费方分别是 src/utils/subject/hentai/index.ts、src/utils/subject/nsfw/index.ts、src/utils/subject/wenku/index.ts它们各自await loadJSON(thirdParty/h.min | nsfw.min | wenku.min)后转换为领域模型。读这些 utility比读原始 JSON 更能理解数据的业务含义。第 4 步最后手段才读数据文件本身只有上述三步都无法回答问题时才打开数据文件且只读前 20 行Read工具的limit: 20。20 行足以确认字段的数值样例与编码风格如是否压缩为单行、key 命名规律足以支撑对结构的判断。五、实战案例AC 自动机搜索模块如何践行 Token 预算精神数据层的双入口设计解决的是运行期资源体积而 src/utils/ac-search/utils.ts 则从另一个角度示范了本指南的核心精神——对昂贵资源的敬畏与懒加载策略。该模块用lazy-aho-corasick构建多模式匹配AC 自动机用于条目中文名/别名 → 条目 id的实时联想搜索其数据来源正是体积最大的substrings/系列 JSONsetTimeout(async () { addon await loadJSON(substrings/addon) alias await loadJSON(substrings/alias) anime await loadJSON(substrings/anime) // ... }, 0)源码注释直接点出了约束初始化需要好几秒需要触发后延迟初始化待下一次再用以及安卓环境一次性初始化太多词条会卡死所以下面做了分组初始化。为了控制初始化开销代码对词条做了多重过滤过滤长度大于 8 或小于等于 1 的条目名命中率很低过滤IGNORE_ITEMS黑名单过滤带特殊符号的条目REG_SPEC用户手动输入的命中率低。这与 Token 预算规则是同构的思维模式识别出体积巨大但有效信息密度低的资源用阈值过滤 延迟加载 分批处理来换取性能与成本的可控。在 Agent 场景下等价手段就是50KB 阈值 路径黑名单 前 20 行限制。六、规则如何与团队 Agent 工作流协同落地在 Bangumi 仓库中context-budget.md并非孤立文件它与.claude/目录下的其他文档构成一套完整的 Agent 协作体系.claude/docs/token-budget.md 是同一规则的精简版挂在 CLAUDE.md 的按需读取索引表中供场景触发时查阅.claude/docs/architecture.md 提供了项目全景技术栈、目录结构、多环境切换、路径别名让 Agent 在不读大文件的前提下快速建立地图CLAUDE.md 明确详细规范按需读取、不要一次性全部加载并规定文档维护原则——改了什么就更新什么。这套组合拳的实际效果是Agent 每次会话只需要按任务类型加载对应文档页面改screen.md、组件改component.md、Store 改store.md而 Token 预算规则像一道安全闸确保任何一次按需加载都不会误触巨型数据文件。若要在其他大型仓库复刻这套实践可以提炼为四条通用规则先测量后设限用du -sh摸清资源分布把超阈值路径写进黑名单Bangumi 的阈值是 50KB。黑名单 白名单并存明确禁止读什么src/assets/json/、node_modules/、构建产物同时明确可以读什么src/源码、根配置、类型定义。以类型与消费方替代内容类型定义、import 语句、处理逻辑三件套通常足以回答 90% 的数据相关问题。把规则文档化并纳入索引像token-budget.md一样挂在主文档的按需读取表中让规则本身可被发现、可被执行。结语Token 预算的本质不是少读书而是读对书。Bangumi32 用一份不到 40 行的context-budget.md将路径黑名单 替代读取策略 四步数据结构推理法固化成了团队与 AI Agent 的共同约定而在 src/assets/json/index.ts 的memo缓存、src/assets/json/index.web.ts 的按需 fetch、src/utils/ac-search/utils.ts 的延迟分组初始化中同一套敬畏大资源的思想早已内化进了产品代码本身。对任何承载海量静态数据的前端/RN 仓库而言这都是一份可直接借鉴的上下文工程范本。【免费下载链接】Bangumi:electron: An unofficial https://bgm.tv ui first app client for Android and iOS, built with React Native. 一个无广告、以爱好为驱动、不以盈利为目的、专门做 ACG 的类似豆瓣的追番记录bgm.tv 第三方客户端。为移动端重新设计内置大量加强的网页端难以实现的功能且提供了相当的自定义选项。 目前已适配 iOS / Android。项目地址: https://gitcode.com/GitHub_Trending/ba/Bangumi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考