lora-sys 团队级 Web 开发工作手册
基本原则
将此文件作为所有 Web 工作的强制交付流程。先理解当前项目与用户目标，再形成计划，随后实施、验证、隔离审查并交付。不要为“技术新”而迁移稳定架构，不要在未被要求时扩大任务，不要用看起来完成的 UI 代替底层已完成的工作。
优先复用当前项目成熟工具、上游模式与已被充分验证的实现。不要为了拥有代码而重写标准聊天 UI、Canvas 行为、流式辅助能力或服务商集成。不要添加不存在的提供商、协议、研究对象或未来产品模式的抽象。保持显式状态转换，隔离第三方实现差异，保持 Canvas 和高频交互在长任务中可响应。
必做工作流
按以下顺序工作；除纯文案、配置或非常小的已验证修复外，不得跳过其中的计划、验收和隔离审查。
- 识别任务和现状。 阅读当前仓库的约定、脚本、锁文件、现有组件、依赖与部署配置。判断任务属于新建、改造、修复、性能/体验优化、审查、发布准备或部署。
- 确认当前技术事实。 在新建项目、升级依赖或使用不熟悉 API 前，查阅相关框架与工具的官方文档；不得根据记忆中的版本、命令或 API 编写实现。
- 先输出计划。 在实施前给出计划的简洁主上下文摘要。需要时使用平台可用的计划工作流展开细节。计划应按任务规模说明：目标和非目标、用户流/信息架构、选型依据、页面/组件、状态与数据/API、依赖变更、风险、验收项，以及部署状态。
- 实施最小正确变更。 按当前项目的结构、命名、格式化、脚本和已有设计语言实施。若发现相邻问题，记录而非顺手扩张当前任务。
- 执行质量验收。 运行现有的类型检查、构建和相关测试；验证成功、失败、空、加载和异常路径；完成截图、移动端、交互、性能、SEO 与无障碍检查。读取
references/quality-gates.md。 - 执行严格隔离对抗审查。 每轮实现或修复后必须遵守
references/review-protocol.md。只修复经源代码或运行事实验证为真的问题，并在修复后复验。 - 按证据交付。 汇报已完成内容、验证证据、修复的真实审查问题、仍存限制和后续可选工作。不要把未执行的检查表述为已通过。
技术选型与工具链
先保留现有项目的合理架构。仅在新建项目或确有选型/迁移必要时，遵循下表并读取 references/stack-selection.md。在选择前，核验当前官方文档、当前稳定版本、项目兼容性与现有脚本。
| 需求特征 | 默认优先选择 | 决策要点 |
|---|---|---|
| 内容站、SEO、SSR、服务端组件或成熟 React 全栈生态 | Next.js | 优先评估渲染、缓存、路由和服务端边界。 |
| 高交互 SPA、营销页、纯前端工具 | Vite | 优先简洁、快速开发和客户端体验。 |
| 全栈 React、Server Functions、端到端类型安全或深度 TanStack 工作流 | TanStack Start | 优先评估现有 TanStack 集成与服务端需求。 |
| 路由、查询/缓存、数据表格 | TanStack Router、Query、Table | 不为已有成熟实现制造无理由迁移。 |
| 3D 场景、空间交互、WebGL 体验 | React Three Fiber | 结合性能预算、降级策略与可访问替代方案设计。 |
| TypeScript 异步流程、错误建模、验证、服务端/领域工作流 | Effect 生态 | 默认评估并优先采用；仅在复杂度、兼容性或项目约束证明不适合时不用。 |
Vite+ 优先规则： 对适用 Web 项目，优先使用 Vite+（vp）作为统一工具链入口。实际开始前，查阅 Vite+ 官方文档与当前项目兼容性；不得把某个 vp 命令、插件或兼容性假设固化为永久规则。使用 Next.js 或其他已有脚手架时，先验证 Vite+ 是否适用，再决定保留项目既有工具或引入 vp。
实现标准
遵循以下不可协商标准；有关 UI、动效和常见问题的扩展规则按需读取相应参考文件。
- 类型与输入： 尽量利用 TypeScript 推导；避免
any；在未知外部输入进入系统时验证其结构、语义和错误路径。Effect 采用与否都不改变这一要求。 - 状态诚实： Spinner 仅表示真实工作尚未完成；成功只在底层任务完成后显示；草稿不得伪装成已应用；断开的 Agent 或服务不得伪装成活跃。
- 注释与可维护性： 注释只解释意图、约束或非直观行为，不复述显然代码。服务商和绘图/Canvas 特性不得泄漏进通用产品状态。
- 可用性与响应式： 保持可见焦点、键盘可达、足够的实际背景对比度、清晰的页面逃生路径和移动优先布局。读取
references/design-motion.md。 - 用户可见变更证据： 对 UI 改动，在可行时提供变更前后截图。动效、时序、拖放或多步交互是重点时，提供短录屏或等效的可运行证据。
- 媒体资产： 不将大型图片、视频或其他媒体直接塞入构建目录；使用项目现有或已确认的资产存储方案，并将源文件保存在构建目录之外。不要把任意特定存储路径、上传命令或地图服务写成跨项目硬规则。
Git、PR 与自动审查
遵循仓库现有的提交、分支、代码格式与 Pull Request 约定。可以为已完成、可验证的改动创建本地提交；除非用户明确要求，不得创建 Pull Request。 用户要求 PR 时，一个 PR 只保持一个主要关注点。
对自动审查结果，将其视为有待验证的主张。仅当结论与源代码、运行产物或明确事实一致时修复；不要为取悦机器人而更改正确代码。所有真实问题的修复必须进入同一轮验收与严格隔离对抗审查。
部署与发布门禁
部署、生产发布、推送生产环境、购买资源、创建付费服务或其他外部不可逆操作，均需要在操作前取得用户在本次任务中的明确确认。可以自行完成部署准备、环境检查、构建、预览和发布方案，但不得把“用户此前授权自主开发”理解为发布授权。
部署具体平台、域名、环境变量、预览策略、回滚与权限，必须在相应项目中依据实际环境决定；不要在此通用技能中猜测或写死。
参考文件导航
| 文件 | 何时读取 |
|---|---|
references/stack-selection.md |
新项目、框架/工具选型、升级依赖、评估 Vite+、TanStack、Effect 或 React Three Fiber 时。 |
references/design-motion.md |
创建或改造用户可见界面、设计系统、主题、动效、可访问体验时。 |
references/quality-gates.md |
每次实现、修复、性能优化、交付或发布准备完成后。 |
references/common-pitfalls.md |
遇到视觉接缝、对比度、主题、导航、路由、状态引用、链接或选择器问题时。 |
references/review-protocol.md |
每轮实现或修复完成后；必须执行。 |
禁止事项
- 不要跳过计划而直接开始中大型 Web 实现。
- 不要把框架、版本、路由或部署命令的旧记忆当作当前事实。
- 不要擅自创建 Pull Request，或在没有本次明确确认时部署/发布。
- 不要伪造测试、截图、性能、SEO、无障碍或审查通过结论。
- 不要让对抗审查者读取用户需求、计划、主上下文、实现说明、Git 历史、既有测试或此前审查结论。
- 不要无理由重写成熟能力、引入多余依赖或在修复时扩张任务范围。
- 不要用透明/图片/滚动背景上的不确定文字对比度、不可到达的导航或“假成功”UI 交付产品。
此技能将“快速完成”定义为：以最小必要变更交付真实运行、可验证、可维护且没有假状态的 Web 体验。