Reflex 仓库 Coding Agent 指南全解析从任务规划到提交的工程化规范【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex导读AGENTS.md 是 Reflex 开源仓库为编码 Agent以及人类贡献者量身定制的开发规范文档覆盖了先规划后编码的工作流、基于 uv 的统一命令体系、monorepo 目录布局、代码风格约束、单元与集成测试规范、.pyi 类型存根维护、changelog 片段机制以及破坏性变更的弃用策略。本文以该文档为骨架逐条结合仓库内的真实源码与配置文件展开剖析帮助你在向 Reflex 提交代码、修复 Bug 或新增特性时一次通过 CI 与人工审查。仓库定位编译到 React 的 Python Web 框架 monorepoAGENTS.md 开门见山给出了仓库的本质Reflex: Python webframeworkcompiling to React. Monorepo using uv workspace — main package inreflex/, sub-packages inpackages/, docs site indocs/.这意味着三件事框架而非脚手架Reflex 是编译型框架Python 代码最终被编译为 React 前端核心逻辑分布在reflex/主包中app、state、compiler、components、utils、istate 等模块。uv workspace monorepo整个仓库用 uv workspace 管理多个包pyproject.toml 中的[tool.uv.workspace]声明了packages/*、docs/app、docs/package等工作区成员同时通过[tool.uv.sources]将reflex-base、reflex-components-*、reflex-release等全部内部包指向工作区本地源码。文档站点独立成包docs/本身是独立的工作区成员说明文档建设与主框架同步演进。工作流三原则AGENTS.md 定义的核心工作流只有三步但每一步都有硬性要求先规划Plan first任务必须在写代码前被清晰定义需求不明确时先与用户对齐细节禁止产出面条式代码sloppy/spaghetti code。Bugfix 先写回归测试修复 Bug 前先写一个会失败的回归测试再用修复让它变绿——这是 TDD 在框架仓库中的强制落地。实现后做对抗性审查adversarial reviewer把自己当成挑剔的审查者对照本文件的每一条规则逐项核查 diff按编号指出问题然后等待用户请求后续修改而不是擅自连续改。这套流程与仓库的 CI 门槛呼应任何改动最终都要过 pyproject.toml 中配置的 ruff、pyright、pytest-covfail_under 72三道关。统一命令入口一切用 uv绝不裸调 pythonAGENTS.md 的第一条硬性约定是Useuvfor everything — never barepythonorpython3。这也是 CONTRIBUTING.md 一贯主张的工程约束原因在于 uv 能严格复现 uv.lock 锁定的依赖树保证本地环境与 CI 一致。文档给出的完整命令清单及逐条解读如下命令作用仓库中的落地依据uv sync安装全部依赖含 dev 依赖组dev 依赖定义于 pyproject.toml 的[dependency-groups]包含 ruff、pyright、playwright、selenium、pytest-* 等uv run pytest tests/units --cov --no-cov-on-fail --cov-report跑单元测试并要求覆盖率 ≥72%[tool.coverage.report]中fail_under 72、branch trueuv run pytest tests/integration跑集成测试较慢集成测试位于 tests/integration内含 Selenium 与 Playwright 两套uv run ruff check .静态 lint[tool.ruff]开启lint.select [ALL]并显式 ignore 一批规则uv run ruff format .代码格式化同一份 ruff 配置uv run pyright reflex tests类型检查[tool.pyright]配置了全部extraPaths与 excludeuv run python scripts/check_min_deps.py校验每个包声明的最低依赖版本可用脚本详解见 scripts/check_min_deps.pyuv run python scripts/check_min_deps.py --check-dev-pins [pkg]禁止已发布元数据中出现*.dev依赖 pin发布工作流通过reflex-release check-dev-pins执行同一道闸门见 packages/reflex-release/src/reflex_release/cli.pyuv run reflex-release sync编辑[tool.reflex-release]或模板后重新生成发布工作流配置见 pyproject.toml 的[tool.reflex-release]uv run python scripts/make_pyi.py重新生成 .pyi 类型存根脚本见 scripts/make_pyi.pyuv run pre-commit run --all-files跑全部 pre-commit 钩子dev 依赖组包含pre-commitcheck_min_deps.py 的底层原理这份脚本值得单独展开因为它体现了 Reflex 对声明的最低依赖版本必须真实可用的较真态度。根据 scripts/check_min_deps.py 顶部的模块文档对每个可检查包根reflex包 packages/*子包在两个隔离的 virtualenv中安装一个按--resolution lowest-direct解析到声明的最低版本一个解析到最新兼容版本依赖均从 PyPI 获取--no-sources绝不使用本地工作区在两种环境下分别对包源码跑 pyright只比较增量错误——即只出现在最低版本环境下的错误才算失败因为它意味着代码用到了比声明的下界更新的 API例如声明pydantic 1.10却调用了 pydantic 2.x 的接口*.dev版本 pin 是例外当某个兄弟工作区包尚未发布时脚本会从本地 checkout 构建 wheel 放入临时--find-links索引仅对该 pin 放行其余依赖仍强制从 PyPI 解析。理解了这一点就能明白为什么 AGENTS.md 要求所有内部包依赖都走并接受--check-dev-pins闸门——它们共同守护发布元数据的可安装性。目录布局速览AGENTS.md 给出了一张极简地图reflex/ # 主框架包app, state, compiler, components, utils, istate packages/ # workspace 子包reflex-base, reflex-components-*, reflex-docgen, reflex-components-internal tests/units/ # 单元测试镜像源码树 tests/integration/ # Selenium 集成测试devprod 两种模式运行 tests_playwright/ # Playwright 集成测试新测试优先放这里 tests/benchmarks/ # 性能基准 docs/ # 文档站点独立 workspace 成员对照实际目录可以验证主包 reflex/ 下确实按app_mixins、compiler、components、istate、middleware、utils、vars等模块组织packages/ 下是 reflex-base、reflex-components-code/core/radix/recharts 等近 20 个子包tests/units/ 按模块镜像组织tests/integration/tests_playwright/ 存放 Playwright 用例。代码风格约束为框架而生的具体规范AGENTS.md 的代码风格条目不多但每一条都针对框架维护的实际痛点简洁稳健Reflex 是被多种方式使用的框架处理边界情况时不引入不必要的复杂度性能敏感避免次优模式例如遍历 dict 按身份找值如果某个操作无法高效完成应建议重构数据结构或 API 而不是打补丁修根因而非贴膏药不要用昂贵的 workaround如isinstance检查掩盖类型层面的问题信任上游校验不要重复校验或过度防御以 CPU 周期思考避免无谓的数据拷贝、冗余分配和多余间接层抽取重复代码重复逻辑收敛为带参数的辅助函数禁止块注释不允许# --- Section ---或# 式分隔注释只保留普通行内注释——这与[tool.ruff]配置中 ignore 列表之外的严格规则形成配合谨慎新增公共 API新公共 API 必须被文档化并长期支持Google 风格 docstring所有函数需遵循一句话摘要 可选细节 Args/Returns或 Yields/Raises结构对应[tool.ruff]中lint.pydocstyle.convention google导入规范模块顶部按 isort 顺序导入仅当必须避免循环依赖时才使用行内导入。测试规范单元测试与集成测试的分工单元测试镜像源码树单元测试位于 tests/units/规范要点测试函数写在模块级不包在类里测试文件按被测模块命名并保留子目录结构例如reflex/istate/manager.py对应tests/units/istate/test_manager.py对子包则保留src/之下的路径如packages/reflex-base/src/reflex_base/event/context.py对应tests/units/reflex_base/event/test_context.py。这套命名约定让测试与源码的映射关系零成本可查也与 pyproject.toml 中[tool.coverage.run]的source列表一致覆盖 reflex 与全部 reflex_* 包。集成测试AppHarness Playwright 模式集成测试优先使用 Playwrighttests/integration/tests_playwright/因为它比 Selenium 更快更稳。AGENTS.md 给出的标准范式是应用以工厂函数形式定义通过AppHarness运行def SomeApp(): import reflex as rx class State(rx.State): value: str def index(): return rx.box(rx.text(State.value)) app rx.App() app.add_page(index) pytest.fixture(scopemodule) def some_app(tmp_path_factory) - Generator[AppHarness, None, None]: with AppHarness.create( roottmp_path_factory.mktemp(some_app), app_sourceSomeApp ) as harness: yield harnessAppHarness的真实实现在 reflex/testing.py它是一个 dataclass持有app_source函数、模块、原始源码字符串或functools.partial、app_module、app_asgi、frontend_url、前后端进程与线程等字段。create()类方法负责在临时目录落地应用并派生app_name——当app_source是字符串时必须显式传入app_name否则直接抛ValueError。测试内部用AppHarness._poll_for轮询前端可达性并把frontend_url写回config.deploy_url。Playwright 用例通过内置的pagefixture 导航到harness.frontend_url进行断言。此外 tests/integration/utils.py 提供了三组高频工具值得在写测试前先了解轮询与导航poll_for_navigation以上下文管理器形式等待 URL 变化事件顺序断言poll_assert_event_order/poll_assert_relative_event_order支持精确序列和第几次出现先于第几次出现的相对顺序断言OrderingRule用于验证事件链的时序存储访问LocalStorage/SessionStorage封装了浏览器localStorage/sessionStorage的读写清删。AGENTS.md 还特别提醒集成测试很慢琐碎功能应扩展现有测试应用而非新建多个测试用例共用同一个 app 是允许的。.pyi 类型存根只提交哈希不提交存根修改或新增组件后必须运行uv run python scripts/make_pyi.py并提交 pyi_hashes.json而不是.pyi文件本身。这份哈希文件充当存根内容指纹CI 用它检测存根是否与源码漂移。若 diff 删除了大量模块文档给出的处理路径是先uv sync删除.pyi_generator_last_run标记文件再重新生成。pyproject.toml 中[tool.hatch.build]的artifacts [/reflex/**/*.pyi]说明这些未提交的存根会在构建时被收集进 wheel。Changelog 片段news fragments面向下游用户的一两句话凡影响用户的变更都需要在所触碰包的news/目录下新增片段根reflex包对应仓库根目录的 news/命名规则为PR号.type.md或在 PR 号未知时用slug.type.md。类型固定为breaking、deprecation、feature、bugfix、performance、docs、misc。写作要求非常明确写给外部下游用户不是写给 reviewer动机、叙述与实现细节属于 PR 和 commit message片段只保留一两句话说明改了什么、对用户意味着什么简洁是针对叙述不是针对实质真正对下游有用的内容新特性的简短用法示例、弃用用法到新用法的前后对比值得放进片段一旦超过几句话加一个小代码块就该升级为文档——写进docs/并在片段里给出链接。仓库根目录 news/6934.bugfix.md 是一份真实样例它用一句话描述了共享状态更新现在能到达连接到其他后端实例的客户端这一修复及其背景正是面向下游用户的简洁叙事的范本。这些片段由 towncrier 聚合进各包 CHANGELOG.mdpyproject.toml 中[tool.towncrier]及[[tool.towncrier.type]]段落为 monorepo 配置了上述七种片段目录与标题。CI 要求PR 触碰了哪个包的源码就必须为那个包提供片段只有skip-changelog标签可以豁免确实非面向用户的改动。破坏性变更与弃用给下游留退路AGENTS.md 的立场是Reflex 有下游用户不要破坏他们弃用期间必须提供回退路径并给出两种弃用手段。运行时弃用警告console.deprecate()from reflex_base.utils import console console.deprecate( feature_nameOldFeature, reasonUse NewFeature instead., deprecation_versionnext dot version of latest git tag, removal_version1.0, )版本号的约定很具体deprecation_version取最新 git tag 的下一个 dot 版本例如 tagv0.7.3→0.7.4必要时先git fetch --tagsremoval_version默认取下一个大版本。在 packages/reflex-base/src/reflex_base/utils/console.py 中可以看到deprecate的真实实现它会通过_get_first_non_framework_frame()向上回溯调用栈找到第一个不属于框架内部的调用帧把用户代码的文件名与行号拼进警告消息默认dedupeTrue时以feature_name 位置为键去重避免同一处弃用刷屏输出走 rich 的黄色DeprecationWarning前缀并视配置同步写入日志文件。类型级弃用typing_extensions.deprecated对已弃用的方法或重载做类型级标记时使用typing_extensions.deprecated且必须放在TYPE_CHECKING守卫内以避免双重警告from __future__ import annotations from typing import TYPE_CHECKING if TYPE_CHECKING: from typing_extensions import deprecated deprecated(Use new_method() instead) def old_method(self) - str: ...提交前检查清单AGENTS.md 在结尾给出 7 条可执行的提交门槛测试通过且覆盖率达标≥72%见 pyproject.toml 的[tool.coverage.report]uv run ruff check .与uv run ruff format .干净uv run pyright reflex tests通过组件有改动时更新 pyi_hashes.json面向用户的行为变化需同步更新文档docs/是独立工作区成员面向用户的变更需新增 news 片段引入破坏性变更需添加弃用警告。总结把规范变成可执行的工程资产AGENTS.md 之所以适合作为 Coding Agent 的操作手册在于它不空谈原则每一条规范都对应着仓库中可验证的落地设施——uv workspace 与锁文件保证环境可复现fail_under 72的覆盖率闸门、check_min_deps.py的最低版本校验、pyi_hashes.json的存根指纹、towncrier 的片段聚合、console.deprecate的调用栈定位与去重共同构成了一套先规划 → 测试先行 → 对抗性自审 → 工具链全绿 → 面向下游的变更记录的闭环。对想要为 Reflex 贡献代码的人来说逐条执行这份清单就是最快通过 review 的路径。【免费下载链接】reflex️ Web apps in pure Python 项目地址: https://gitcode.com/GitHub_Trending/re/reflex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
