贡献指南

开发环境

uv venv
uv sync --all-groups

文档被视为代码库的一部分。出现以下变更时，默认必须同步更新 docs/：

写作分层、双语策略和评审清单见文档规范。

just lint

或：

uv run pre-commit run --all-files

just test

如修改 admin-frontend 的关键后台业务流、受保护登录链路、E2E 选择器契约或 GitHub Actions E2E 集成，额外执行：

cd tests/e2e
npm ci
npm run lint
npm run typecheck
npm test
npm run test:headed
npm run test:all

补充说明：

GitHub Actions 的 e2e job 会为隔离 Docker 栈生成临时管理员凭据，不依赖仓库 secrets。
GitHub Actions 的 e2e job 还会先把仓库根目录的 .env.example 复制为 .env，因为当前 docker-compose.yml 的 ai-service 仍通过 env_file: .env 读取基础运行配置。
本地默认 Docker 模式必须提供 PLAYWRIGHT_ADMIN_EMAIL、PLAYWRIGHT_ADMIN_USERNAME、PLAYWRIGHT_ADMIN_PASSWORD 三元组；如果还设置了 PLAYWRIGHT_ADMIN_IDENTIFIER，它必须与同一次 bootstrap 的 username 或 email 一致。
如果接入已有环境，则改用 PLAYWRIGHT_SKIP_STACK_BOOT=1 加 PLAYWRIGHT_ADMIN_IDENTIFIER、PLAYWRIGHT_ADMIN_PASSWORD；未显式设置 PLAYWRIGHT_STACK_MODE 时，这条路径会默认等待本地 dev 栈的 8000/5174，非默认地址请继续显式设置 URL。
npm run test:headed 默认串行执行；当前本地有头调试环境里，并发 Chromium 更容易在截图型用例上触发偶发协议错误。
npm run test:all 会先跑业务流套件，再单独跑视觉回归，并分别保留 workflow/visual 两套报告目录，避免视觉快照与并发造数的 workflow 相互干扰。
tests/ 现在是仓库统一测试根目录，其中 tests/fixtures/shared/ 承载跨 pytest / Playwright 共用资源，tests/e2e/ 仍是独立 Node 包，不属于 pytest 套件。

cd demo-frontend
npm ci
npm run build

cd admin-frontend
npm ci
npm run build

补充要求：

如果改动 admin-frontend/studio 的共享 provider、overlay 原语或 tooltip 组合方式，先阅读 Admin Shell 结构约束里的 Studio 运行时 Provider 护栏 小节。

uv run --group docs mkdocs build

如需本地预览：

just docs-serve

uv sync --all-groups
just lint
just test
just test-integration
uv run --group docs mkdocs build

提交包含文档的变更前，至少执行以下检查：