Bilibili Evolved 仓库开发指南面向编码 Agent 的 AGENTS.md 深度解读与实践【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-EvolvedBilibili Evolved 是一个基于 Web 前端技术构建的哔哩哔哩增强油猴脚本userscript。本文以仓库根目录的 AGENTS.md 为核心骨架结合 CONTRIBUTING.md、开发服务源码与真实组件实现系统讲解该仓库的项目结构、开发环境搭建、dev-server 调试协议、组件与插件编写规范、代码风格、验证流程以及分支与提交约定。阅读本文后你将能够独立地在本地完成该仓库的开发环境配置正确区分组件与插件的定位使用命令行与 WebSocket 驱动 dev-server 完成功能编译、监听、调试与脚手架创建并通过pnpm run type、pnpm run lint-check等命令通过代码检查最终以preview-features/preview-fixes为基准确发起 Pull Request。AGENTS.md 在仓库中的定位AGENTS.md 是给编码 Agent 的仓库级专项指导文件。它在文档体系中处于第二步的位置先阅读 CONTRIBUTING.md 了解贡献全流程再把 AGENTS.md 作为实现与验证阶段的实操清单。两者的分工可以概括为CONTRIBUTING.md面向人类的完整贡献指南覆盖环境搭建、Tampermonkey 本地调试脚本配置、本体/组件/插件的开发与新增流程、可用 API 资源、代码检查与 PR 提交。AGENTS.md面向 AI 编码 Agent 的精简检查单用更结构化的条目把项目结构、命令、规范、验证标准浓缩成可执行的约束。因此任何在本仓库执行修改任务的 Agent都应先通过 CONTRIBUTING.md 建立全局认知再逐条对照 AGENTS.md 的清单落地实现。项目结构理解三个代码区的职责边界AGENTS.md 首先明确了仓库的顶层布局核心是理解本体与功能分离的架构src/油猴脚本本体userscript core包含内置组件、共享运行时 API、设置 UI以及随主脚本一起发布的代码。开发时会在dist/下生成开发版脚本bilibili-evolved.dev.user.js。registry/lib/components/可安装组件installable components源码。新组件应放入对应的类别目录如feeds/、live/、style/、touch/、utils/、video/并以index.ts作为 webpack 编译入口——webpack 配置会搜索所有index.ts作为组件入口该文件名不可更改。registry/lib/plugins/插件源码。当某个功能只有作为另一个组件的扩展才有意义时应实现为插件而非组件。registry/lib/docs/third-party.ts第三方组件登记入口。希望保持独立于主仓库的组件通过向该文件中的数组追加信息来注册而不是把外部组件注册逻辑混入仓库内源码修改。dist/与registry/dist/构建产物。开发分支不应保留生成的 dist 文件preview、master、master-cdn等发布输出分支的产物由 CI 构建产生。doc/features/由元数据生成的功能文档输出。仅在任务明确涉及生成文档或发布准备时才更新普通功能或修复 PR 中不要手动修改。从实现看src/components/下也有一部分组件如define.ts、types.ts这些是内置组件无法独立安装/卸载真正可独立安装卸载的组件都在registry/lib/components/下。这一区分是理解本体 vs 功能的关键。开发环境搭建与常用命令环境前提与依赖安装根据 CONTRIBUTING.md环境需要 Node.js 14.0、Visual Studio Code 与 pnpm 8.9.0。AGENTS.md 强调包管理器是pnpm根目录 package.json 中packageManager锁定为pnpm10.3.0并给出两条安装命令# 安装根目录依赖本体 pnpm install # 构建 registry 功能时需要安装 registry 依赖 cd registry pnpm install当对任务命令存疑时以.vscode/tasks.json中定义的 VS Code Tasks 为本地任务命令的事实来源npm scripts 仅用于 CI。常用命令速查AGENTS.md 列出的常用命令如下它们在根目录 package.json 的scripts中均有对应实现# TypeScript 类型检查对应 scripts.type: tsc -p tsconfig.type-check.json --noEmit pnpm run type # ESLint 风格检查对应 scripts.lint-check: eslint . --ext .ts,.vue pnpm run lint-check # 启动开发服务核心 watcher WebSocket HTTP pnpm tsx dev-tools/dev-server/index.ts # 查询当前被监听的功能会话 pnpm tsx dev-tools/dev-server/command.ts sessions # 优雅关闭开发服务 pnpm tsx dev-tools/dev-server/command.ts shutdown其中pnpm tsx dev-tools/dev-server/index.ts的启动逻辑见 dev-tools/dev-server/index.ts依次启动 HTTP 服务器、核心 watcher自动编译开发版本体与 WebSocket 服务器。启动成功后终端会输出类似DevServer 已启动, 端口: 23333 本体编译中... (...可能有一长串输出) 本体已编译: 一段 hashDev Server 深入HTTP、WebSocket 与 CLI 三条通道开发服务是本地调试的核心设施dev-tools/dev-server/README.md 给出了完整协议说明。它通过三条通道协同工作HTTP静态资源与虚拟编译 URLHTTP 服务器只为本体产物服务根目录静态文件dist/*映射到核心 userscript 输出。registry/dist/components/id.js与registry/dist/plugins/id.js是虚拟输出 URL当内存中缺少对应产物时触发按需编译build-on-request随后从内存返回编译结果其他/registry/*路径不从磁盘提供。HTTP 不暴露控制 API所有控制能力都走 WebSocket。WebSocket命令与事件控制面默认地址为ws://localhost:23333端口见 dev-tools/dev-server/config.ts 中的默认值23333。客户端可发送以下命令载荷完整类型定义见 dev-tools/dev-server/payload.ts{ type: queryFeatureSessions }{ type: shutdownServer, requestId: ... }{ type: buildFeature, kind: component, id: style/hide/banner, requestId: ... }{ type: startFeatureSession, kind: plugin, id: video/player/speed, requestId: ... }{ type: stopFeatureSession, kind: component, id: style/hide/banner, requestId: ... }{ type: startDebugFeature, kind: component, id: style/hide/banner, targetClientId: dev-client-1, requestId: ... }{ type: createFeature, kind: component, id: style/my-feature, name: myFeature, displayName: My Feature, authorName: Author Name, authorLink: https://example.com, description: Feature description., requestId: ... }服务器侧会推送以下事件serverReady连接建立时的初始事件携带clientId与当前激活的featureSessions。featureSessionsChanged被监听的功能路径发生变化。itemUpdate被监听功能编译完成DevClient 应进行更新。featureBuilt显式构建或监听构建完成。featureBuildFailed显式构建失败。serverStop服务器正在关闭DevClient 应恢复 dev URL 并关闭 socket。commandResult针对带requestId命令的响应。CLIcommand.ts 命令行客户端不需要手写 WebSocket 客户端时直接使用命令客户端开发服务运行期间pnpm tsx dev-tools/dev-server/command.ts sessions pnpm tsx dev-tools/dev-server/command.ts build component style/hide/banner pnpm tsx dev-tools/dev-server/command.ts watch plugin video/player/speed pnpm tsx dev-tools/dev-server/command.ts stop component style/hide/banner pnpm tsx dev-tools/dev-server/command.ts start-debug component style/hide/banner dev-client-1 pnpm tsx dev-tools/dev-server/command.ts stop-debug component style/hide/banner pnpm tsx dev-tools/dev-server/command.ts shutdown各命令的参数细节在 dev-tools/dev-server/command.ts 中有完整实现与用法输出build component|plugin id [development|production]单功能编译第二个可选参数决定 development 还是 production 模式其余值一律视为 development。watch component|plugin id启动监听会话代码改动后自动重编译。stop component|plugin id停止监听会话。start-debug component|plugin id [targetClientId]将编译产物定向推送给指定clientId的 DevClient 进行页面调试。stop-debug component|plugin id结束调试会话。sessions列出当前所有被监听的功能会话。shutdown优雅关闭整个开发服务。create component|plugin id name displayName authorName [authorLink] [description]创建功能脚手架见下文。shutdown命令会先响应命令客户端广播serverStop再依次关闭核心 watcher、功能 watcher、WebSocket 连接与 HTTP 服务器因此完成开发后应使用它退出而不是手动结束 Node.js 子进程。配置项dev/dev-server.jsondev-tools/dev-server/config.ts 展示了配置合并逻辑默认值{ port: 23333, maxWatchers: 16 }与可选文件dev/dev-server.json中的配置做浅合并后者可覆盖前者。也就是说可以通过在仓库根目录创建dev/dev-server.json自定义端口与最大 watcher 数例如{ port: 23333, maxWatchers: 16 }组件与插件编写规范AGENTS.md 对组件与插件的编写给出了明确约束下面逐条结合源码展开。用 defineComponentMetadata 定义组件组件必须通过defineComponentMetadata定义并导出component对象。src/components/define.ts 中该函数只是一个泛型恒等函数作用是让 TypeScript 根据ComponentMetadata类型对元数据做静态校验。一个真实的组件示例是 registry/lib/components/feeds/filter/index.ts 中的feedsFilter动态过滤器export const component defineComponentMetadata({ name: feedsFilter, displayName: 动态过滤器, entry, tags: [componentsTags.feeds], options, reload: () document.body.classList.remove(disable-feeds-filter), unload: () document.body.classList.add(disable-feeds-filter), urlInclude: [/^https:\/\/t\.bilibili\.com\/$/], plugin: feedsFilterPlugin, })插件则遵循PluginMetadata接口导出plugin对象src/plugins/plugin.ts例如setup函数作为插件初始化入口。AGENTS.md 要求registry/lib/plugins/下的代码遵循既有插件定义模式。关键元数据与生命周期约定author必填新组件必须包含author元数据通常是 GitHub 用户名与主页地址如需注明 AI 辅助开发author可以是数组追加 AI 名称与官网。命名规范name应具体且使用 camelCasedisplayName与选项名应清晰描述功能避免通用标签。index.md即描述若组件带index.md编译时其内容会自动注入description除非该组件的既有模式要求否则不要在元数据中重复编写相同描述。页面匹配用urlInclude/urlExclude不要在手写entry中重复进行页面判断。上述动态过滤器就用urlInclude: [/^https:\/\/t\.bilibili\.com\/$/]限定仅作用于动态首页。entry只做启动必要工作保持entry专注于组件启动时必须完成的事。清理逻辑放unload不要依赖entry的返回值做清理。需要支持关闭/重新开启实时生效的组件必须让reload与unload成对出现。选项定义遵循既有defineOptionsMetadata与options模式见 src/components/types.ts 中OptionsMetadata类型让默认值、标签与校验器与元数据保持一处定义互斥的多选布尔项应建模为单一选项enum 或下拉。样式规范固定的组件样式放入 SCSS 文件不要在业务逻辑中拼接样式字符串。使用instantStyles、styledComponentEntry或toggleStyle保证样式只在预期时机生效。编写 SCSS 前先查找共享 Sass 文件ui/_common.scss可通过import common引入提供全屏、居中之类的通用 mixin。当设置需要控制 CSS 时优先在html或body上切换 class再针对该 class 编写 SCSS。创建新功能的脚手架create命令会调用 dev-tools/dev-server/scaffold.ts 中的createFeature校验 ID 合法性拒绝空值、以/开头、包含..或绝对路径在registry/lib/components/id或registry/lib/plugins/id下创建目录并生成index.ts与index.md。生成的组件模板自带defineComponentMetadata骨架、tags自动取 ID 首段映射为分类标签、author字段插件模板则导出带setup的PluginMetadata。因此新增功能的正确姿势是先create生成骨架再填充业务逻辑与选项。代码风格约定AGENTS.md 的 Code Style 章节对代码风格提出具体要求均与仓库的 ESLintairbnb-base 扩展与 Prettier 配置对应遵循仓库的 ESLint 与 Prettier 配置。除既有 ESLint overrides 覆盖的文件如 Vue 单文件组件与构建相关文件外使用具名导出。控制流语句体保持花括号包裹。保留所修改代码周边的既有 TypeScript、Vue 2 与 SCSS 约定项目当前基于 Vue 2.7见 package.json 依赖。避免不必要的防御性分支、空错误处理、重复状态与一次性抽象。优先复用既有的 Bilibili API 封装、请求辅助、设置辅助、observer 工具、样式工具与 UI 组件而不是重新实现等价行为。能通过稳定 Bilibili API 与既有封装获得数据时不要读取页面内部全局变量或框架内部实现。DOM 选择器作用域应限定在最近的稳定父类或页面区域避免命中无关 B 站 UI 的宽泛选择器。名称与类型必须与行为一致若函数开始返回更宽泛的形状应更新类型与名称而不是重载一个误导性契约。谨慎对待数据单位与 API 失败态不要把失败请求当作成功值缓存字节、比特、数量、ID 与 URL 的语义要保持明确。验证流程本地检查与 CI 生产构建的分工AGENTS.md 要求按变更的风险与范围选择验证方式类型检查pnpm run type。风格检查pnpm run lint-check可自动修复的问题也可运行pnpm run lint。本体核心修改使用 dev-server 的核心 watcher它会自动编译开发版本体。registry 功能修改dev-server 运行期间执行pnpm tsx dev-tools/dev-server/command.ts build component|plugin id。dev-server 自身 TypeScript 修改pnpm exec tsc -p dev-tools/dev-server/tsconfig.json。浏览器行为验证用本地 userscript 在真实浏览器中验证改动后的功能。依赖 API 形状或 B 站灰度变化记录实际自测的页面与账号状态。此外CONTRIBUTING.md 补充了 PR 文件检查命令pnpm run check-pr-files对应 dev-tools/pr-check/ 实现用于发现提交构建产物、手动编辑生成的功能文档、组件/插件描述文件缺失、reload/unload未成对等常见 PR 结构问题。CI 生产构建不要作为常规本地验证重复执行。PR 的 CI 工作流会依次运行pnpm run type→pnpm run lint-check→pnpm run build-core→ 在registry/安装依赖 →pnpm run build-features。仅在显式要求复现 CI 失败、改动共享构建基础设施或准备发布时才在本地执行这些生产构建。当改动影响页面行为时还需打开浏览器控制台检查新增运行时错误并在受影响的页面类型视频、番剧、直播、动态、空间、设置面板等上实测。分支与提交约定AGENTS.md 的 Branches And Commits 章节是提交前必须遵守的约定新功能以preview-features为基线分支。Bug 修复以preview-fixes为基线分支。commit message只需清晰描述改动仓库不强求严格的 conventional commit 格式CONTRIBUTING.md 也明确中英文随意、不做 commitlint 强校验。不要创建 release tag、推送发布分支或执行发布步骤除非任务明确与发布相关。提交仅含源代码修改不要把dist/或registry/dist/产物、无关缓存、profile、本地调试或包管理器输出文件提交上去。面向 Agent 的实操自检清单综合 AGENTS.md 全部章节一个编码 Agent 在本仓库完成任务时应按如下顺序自检已通读 CONTRIBUTING.md并按需阅读 dev-tools/dev-server/README.md 理解协议细节。正确判断改动落点本体在src/可安装组件在registry/lib/components/扩展性插件在registry/lib/plugins/第三方独立组件走 registry/lib/docs/third-party.ts。组件/插件均以index.ts为 webpack 入口用defineComponentMetadata/PluginMetadata定义author齐全命名具体清晰index.md描述不重复。生命周期正确entry只做启动工作页面匹配交给urlInclude/urlExclude清理放unload需要热开关时reload/unload成对。样式进入 SCSS 并复用共享 mixin设置控制 CSS 时用 html/body 上的 class 开关。代码风格与类型契约符合仓库约定不引入宽泛选择器与误导性命名。验证按风险分级执行pnpm run type、pnpm run lint-check必要时通过 dev-server 的build/watch/start-debug驱动功能编译并在真实浏览器与对应页面类型中实测。不手动改生成文件、不提交构建产物分支基于preview-features或preview-fixescommit message 清晰描述改动。【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考