贡献与验证流程

目标：提交能被复现、审阅和持续维护的改动。公开能力见功能概览，具体契约以源码与类型声明为准。

修改前先定位职责

先阅读 README.md、功能概览和相关包的 README，再沿目录结构找到对应模块。应用业务留在 apps/demo，跨应用的稳定能力才进入共享包，官网内容在 apps/website。

只提交本次负责的改动，避免混入无关文件。

一项业务功能的完整交付

1. 在 API 层定义 endpoint、method、输入和输出类型。
2. 为未完成的服务端接口提供同契约 Mock，并验证错误与权限。
3. 在 hook 中组织异步状态，页面通过数据链路读取，避免硬编码业务记录。
4. 注册模块、路由、导航和页面验收入口；多状态页面分别提供预览项。
5. 补齐中英文、深浅主题、键盘可访问性与必要资源。
6. 同步更新对应包文档与公开功能概览。

特性清单与代码在同一提交更新。删除或重命名文件时同步清理旧条目，不能留到“后续补文档”。

选择对应验证

改动	优先验证
类型、业务逻辑	pnpm typecheck、相关单元测试
Mock 与持久化	pnpm exec vitest run apps/demo/mock/browser.test.ts
页面与交互	pnpm test:e2e，并检查中英文与主题
静态演示	pnpm build:demo 后 pnpm test:e2e:static
共享包导出与依赖	pnpm build:packages、pnpm verify:packages
文档和官网	pnpm docs:build，预览检查链接与窄屏

最终集成前的完整基线：

pnpm lint
pnpm typecheck
pnpm test
pnpm build:all
pnpm verify:packages
pnpm test:e2e:static

测试应该证明用户行为或边界，而非逐行重复实现。修复接口错误时覆盖失败状态；修复持久化时验证刷新恢复与写入失败；调整布局时检查实际页面，而非仅看编译成功。

提交与评审

提交信息使用中文，例如 fix: 修复任务筛选后的分页状态。提交前检查暂存区只包含本次负责文件。

评审说明描述触发条件、修改后的行为、验证结果与尚存限制。共享包的版本与发布记录按 Changesets 流程维护；apps/demo 和 apps/website 是私有应用，不作为 npm 包发布。

常见遗漏

本地 workspace 能运行，不保证 npm tarball 有完整依赖与导出，应执行包消费验证。开发 Mock 能用，不保证浏览器构建没有网络回退，应执行静态测试。文档能编译，不保证命令与路径正确，应对照实际脚本和源码检查。遇到无关脏文件只保留，不把它当成清理任务。