Imported from tandong1651399082/skill (SKILL.md). Install upstream with npx skills add tandong1651399082/skill. Copyright stays with the author.

AI 代码质量守卫

按以下规范实施每一次代码变更。若项目已有更严格或已约定的规范，遵循项目规范；不得以本规范为由破坏既有兼容性。

实施前

1. 阅读相关业务代码、类型定义、接口契约、路由、数据库结构、现有测试及已安装依赖，确认真实业务目标、边界条件及异常分支。
2. 先评估项目已有组件库、业务组件、SDK、工具包、中间件和框架能力。能安全满足需求时优先复用，再设计模块职责、数据流、接口影响和验收方式。
3. 复用项目已有的目录约定、组件、样式、状态管理、错误处理和接口封装；不得为单个需求另起一套平行架构。

优先复用，不重复造轮子

• 前端的表单、表格、弹窗、日期选择、上传、校验、通知和布局，优先使用项目已引入的组件库或通用组件；先查阅其 API、无障碍能力和主题规范，再组合使用。
• 后端的鉴权、参数校验、密码处理、日志、缓存、文件处理、分页、数据库访问和序列化，优先使用项目已有的框架能力、成熟工具包或中间件，并遵循项目封装。
• 不得在已有可靠方案可用时手写重复组件、基础工具或协议实现。仅在需求明确要求、现有方案无法满足且评估过兼容性、安全性、维护成本后，才实现自定义方案，并用中文说明原因。
• 引入新依赖前，确认许可证、体积/性能、安全性、维护状态和与现有技术栈的兼容性；能用现有依赖完成时不得随意新增。

文件、模块与组件

• 将每个手写源码文件控制在 300 行以内（空行和注释也计入）。超过时，按单一职责拆成有明确语义的模块、组件、组合式函数、服务、类型或工具文件。
• 不为凑行数机械拆分。每个新文件必须有清晰职责、合理命名和稳定的导入边界；避免循环依赖和只做无意义转发的文件。
• UI 同时包含多个独立职责、可复用区块或复杂交互时，拆分组件；容器组件负责业务编排，展示组件负责渲染和事件抛出。
• 按工程化分层组织代码。常见分层为：页面/组件、业务逻辑或状态、接口服务、类型、通用工具和测试。使用项目已有结构优先。
• 配置、生成文件、第三方代码及项目工具强制生成的文件不做 300 行硬拆分；但不得手工向其中塞入业务逻辑。

文档与中文注释

• 每次新增、删除或明显改变用户可感知功能时，更新 README.md 中对应的功能说明。
• README.md 只写功能作用、入口或使用效果，保持简洁；不要在其中堆放请求字段、响应字段、实现步骤或内部算法。
• 后端实现接口前后都要查阅并更新项目既有 API 文档；不得只依据调用方猜测契约。若项目没有 API 文档，则在约定的 docs 目录创建并维护中文 API 文档。
• API 文档和接口附近的中文文档注释必须说明：接口用途、请求方式与路径、鉴权要求、请求头、每个请求参数的名称/类型/必填性/示例/业务含义/校验规则、每个响应字段的类型/示例/含义、错误码、状态转换和业务约束。
• 所有新增或修改的函数、方法、复杂条件、业务规则和关键数据转换都写准确、可维护的中文注释。注释要解释“为何这样做、业务含义和边界”，不要重复代码字面行为。
• 例如登录接口必须明确：登录用途、请求参数（名称、类型、必填性、含义）、成功响应 content 的字段、失败码及客户端处理方式。

接口与数据契约

• 后端新增或改造接口统一返回以下顶层结构，字段名和层级不得随接口变化：

  {
    "msg": "操作说明或错误信息",
    "code": 401,
    "content": {}
  }

• msg 必须为字符串；code 必须为数字状态码或项目统一业务码；content 必须存在，并且仅使用对象 {} 或数组 []。无数据时按语义返回空对象或空数组，不能省略、设为 null 或改名。

• 成功与失败都使用同一结构。具体成功码、错误码语义和 HTTP 状态码服从项目既有约定；若没有约定，应在接口文档中明确。

• 前后端同步更新类型、校验、错误处理和接口文档；不得假定字段一定存在。对空值、权限不足、重复提交、网络失败和服务端异常作出明确处理。

数据库规范

• 设计或修改表、字段、索引、关联及迁移前，先复用项目的数据访问层、迁移工具和命名约定；不得手写绕过现有工程体系的数据库操作。
• 每个数据库表和字段必须使用准确的中文备注，清楚表达业务含义；状态码、金额单位、时间字段、软删除、创建/更新人等字段必须说明取值规则或单位。
• 迁移脚本要包含必要的注释、默认值、非空约束、索引和回滚策略（若项目迁移工具支持）。同步更新实体、DTO、类型与 API 文档。

开发工具

• 在 Windows 本地执行系统命令时，默认只使用 cmd，不得使用 PowerShell。确有 cmd 无法胜任的脚本能力时，说明原因后再使用其他脚本环境。
• 需要编写辅助脚本、批处理数据、解析文件或自动化校验时，优先使用 Python；脚本完成任务后按“临时内容清理”规则清理或正式化。

反 AI 视觉审美协议

将此协议应用于所有视觉输出，包括图片、插画、UI 布局、页面视觉代码和设计稿描述。以“完美是机器，缺陷是灵魂”为审美准则；在不损害可用性、可访问性、品牌规范和明确业务要求的前提下，严格执行以下规则。

构图不对称

• 禁止把视觉主体置于正中央。采用三分法或极端偏移，并保留至少 30% 的留白或裁切区域。
• 鼓励人物、物体或大标题出框、贴边或边缘截断；不要构造镜像式、绝对均衡的版式。
• 若存在视觉上完全对称的元素，将其旋转或偏移 3 至 5 度；不得影响正文阅读、点击热区或表单对齐。

色彩做旧

• 禁止使用高饱和纯色，如 #FF0000、#0000FF。沿用项目色板时，以低饱和替代色或局部纹理处理保留品牌可识别性。
• 主色调叠加胶片褪色感：色温偏暖约 5%、对比度降低约 10%、阴影偏青。
• 画面必须包含至少一种脏色，例如灰绿、赭石或暗浊蓝；不得形成大面积刺眼纯色块。
• 用纸张、颗粒、网点或可访问的低对比纹理打碎大色块；文本与关键控件仍须满足可读性和对比度要求。

材质与光影

• 禁止平滑渐变和完美描边。使用不规则边缘、纹理或细微磨损替代，不得影响控件边界辨识和键盘焦点样式。
• 为视觉边缘加入约 15% 的颗粒噪点或等效纹理，不要将噪点叠加在正文、表单输入和关键数据上。
• 图片、插画和视觉背景优先使用硬光或侧逆光，拒绝柔光箱式塑料质感；光影不可遮挡信息或降低无障碍对比度。

字体、UI 与克制原则

• 标题字间距拉开至约 150%；正文可使用衬线与无衬线混排，但必须确保项目支持字体加载、中文可读性和响应式排版。
• 页面仍以清晰、克制、可读和一致为优先，沿用项目设计系统、间距、交互状态和组件规范。
• 不使用大面积毛玻璃、过量渐变、夸张光效、无意义动效或堆叠装饰卡片。设计应具有人为取舍与材质感，而非典型 AI 生成式视觉风格。
• 在不干扰功能的非交互角落加入一个克制、模糊的色块或纹理瑕疵，制造轻微的非完美感；不得覆盖内容、误导用户或违背品牌规范。

视觉交付与自检

视觉内容交付时，先输出“祛 AI 矫正后的最终设计稿描述/代码”，再附上“做了哪些反 AI 改动”的简要说明。输出前逐项检查：

• 不存在视觉上完全对称的主要元素；必要元素已做 3 至 5 度偏移或不对称处理。
• 没有大面积纯色块；已通过低饱和色、纹理或颗粒打碎。
• 标题字距约为 150%，正文的字体搭配可读且可用。
• 已加入不影响使用的角落模糊色块或纹理瑕疵。
• 未牺牲可访问性、信息层级、交互反馈、品牌规范和业务目标。

实现与校验

1. 按业务流程逐项核对：输入校验、权限、状态流转、幂等性或重复操作、异常反馈、加载状态以及成功后的界面/数据更新。
2. 运行与改动相称的格式化、类型检查、静态检查、单元测试、构建或手工验收；优先使用项目已配置的命令。
3. 检查调用链和相邻功能，确认变更未破坏已有接口、页面、状态或权限规则。
4. 完成前复核所有受影响的手写代码文件均不超过 300 行；必要时继续拆分。

临时内容清理

• 测试或演示所新增的 mock 数据、mock 接口、假账号、硬编码测试分支和临时降级逻辑，验收后必须删除，不能随正式代码提交。
• 不删除项目原有、仍被其他场景使用的 mock；仅清理本次创建或已确认废弃的内容，并恢复真实数据链路。
• 本次创建的临时脚本、调试页面、截图、日志、迁移辅助文件和一次性工具文件，任务结束前必须删除。确需保留时，必须转为正式、可维护的项目工具并说明用途。

交付前清单

• 功能符合明确的业务需求，异常与边界场景已覆盖。
• 手写源码文件均不超过 300 行，职责拆分合理。
• 新增功能已在 README.md 简要说明作用，README 未混入技术明细。
• 接口详细契约已写在 API 文档或接口附近的中文注释中。
• 相关函数、方法和关键业务逻辑有正确的中文注释。
• 接口响应统一为 msg、code、content，并完成调用方适配。
• 已优先复用现有组件库、工具包和工程能力；新增依赖或自定义实现均有必要性依据。
• API 文档以中文完整说明接口与每个参数；数据库新增或改动字段已有准确中文备注。
• Windows 本地命令使用 cmd；需要辅助脚本时优先使用 Python。
• 视觉内容已通过反 AI 审美协议自检，并在交付中说明具体矫正改动。
• 已通过与改动相称的校验、测试或构建。
• 本次新增 mock 与临时工具均已清理。

交付时简要说明：功能变更、拆分结果、README 更新位置、校验结果，以及未能执行的校验及原因。