AGENTS.md

本文件用于约束后续在本项目内协作的 AI/自动化代理行为。

项目目标

这是一个面向新手的微信小程序项目，目标是：

保持项目结构简单、易懂、易修改
使用 Taro + React + TypeScript 作为核心技术栈
明确这是“微信小程序”项目，不是原生 App 或 H5 项目
所有说明尽量使用中文
在保证可运行的前提下，减少复杂依赖

协作原则

修改代码前，先阅读现有文件，避免无意义重构。
优先做小步修改，保持项目始终可运行。
已确认使用 React + TypeScript，默认采用 Taro 作为微信小程序框架。
不要在 Taro 之外再擅自引入新的大型框架或状态管理库，除非用户明确要求。
对新手不友好的实现方式，要同时补充解释性注释或文档。
涉及配置时，优先使用明确值，并在文档里写清楚用户需要修改的位置。

文件与代码规范

默认使用 UTF-8 编码。
页面、组件和配置命名尽量贴合 Taro 与微信小程序习惯。
目录结构优先采用：
- src/pages/ 放页面
- src/components/ 放可复用组件
- src/utils/ 放工具函数
- src/assets/ 放静态资源
- config/ 放 Taro 构建配置
默认使用 TypeScript 编写业务代码。
样式优先使用 .scss，但保持简单，避免过度抽象。
非必要不新增依赖，尤其避免在项目初期引入复杂状态管理、UI 大全家桶或重型工具链。

主题与组件约定

颜色统一收口到 src/styles/theme.scss，优先使用 CSS 变量，不要在页面和组件里散落写十六进制颜色值。
新增颜色时，先判断是否属于已有语义色：
- 品牌色
- 页面背景色
- 卡片背景色
- 文字主次色
- 警告色
- 危险色
如果某个颜色只在单个页面临时使用，也应优先评估是否值得提升为公共主题变量。
通用 UI 优先拆到 src/components/，尤其是以下类型：
- 按钮
- 卡片
- 底部导航
- 列表项
- 状态块
图标使用保持语义统一：
- 如果页面有“返回上一级页面”操作，优先使用 back.svg
- 如果页面有“加号/新增”操作，优先使用 add.svg
如果一个结构或样式在两个及以上页面/区域重复出现，优先抽成可复用组件，而不是复制粘贴。
组件设计尽量保持“样式可配置、职责单一、命名清晰”，避免做过度复杂的大而全组件。

小程序设计适配约定

本项目是微信小程序，后续收到的设计稿即使来自 App，也不能直接按 App 页面生搬硬套。
设计稿如果是 App 视觉稿，落地时必须同时考虑：
- 手机系统状态栏安全区
- 微信小程序原生胶囊按钮区域
- 微信小程序页面顶部 appbar 的可用空间
顶部按钮、标题、搜索框、头像、返回区等靠近页面顶部的元素，优先基于小程序原生 statusBarHeight、getMenuButtonBoundingClientRect() 等信息定位，而不是只按设计稿静态像素值摆放。
当 App 设计稿顶部结构与微信小程序原生导航区域冲突时，优先保证小程序可用性和对齐关系，再尽量还原设计视觉。
页面评审时，顶部区域要重点检查这几项：
- 是否遮挡原生胶囊
- 是否与原生胶囊水平对齐
- 是否预留了不同机型的顶部安全区
- 是否在真机上仍然成立

修改边界

可以新增或修改当前工作区内与本项目直接相关的文件。
如需删除文件，必须严格遵守工作区已有的删除安全规则。
不得擅自删除目录、批量删除文件、清空文件夹。
不得覆盖用户未明确要求替换的重要配置、密钥或证书文件。

AppID 与发布相关

不要伪造真实 AppID、密钥、证书、域名或后台接口地址。
涉及 AppID 时，优先保留用户提供的真实值。
如果项目需要上线步骤说明，必须同步更新 README.md。

文档要求

每次新增关键功能、配置步骤或部署步骤时，优先同步更新 README.md。
文档写法以“零基础可照做”为标准，避免只写结论不写路径。
如果修改了 Taro 的开发、编译、预览或发布流程，必须更新 README.md 中对应命令和目录说明。

原始设计色板参考

以下颜色可作为设计来源参考，但在代码中应优先映射为 src/styles/theme.scss 中的语义化变量，而不是直接把 color1、color2 这类名称搬进业务代码。

  color1: '#45D989',
  color2: "#00C1AA",
  color3: "#333333",
  color4: "#D3D3D3",
  color6: "#FBF5D5",
  color5: "#FFFFF006",
  color7: "#00C1AA",
  color8: "#FF9F66",
  color9: "#FF7159",
  color10: "#E60012",
  color11: "#00C1AA",
  color12: "#10CFF1",
  color13: "#FF9F66",
  color14: "#FF7159",
  color15: "#F6F6F6",
  color16: "#333333",
  color17: "#FFFFFF",
  color18: "#FFFFFF",
  color19: "#FFFFFF",
  color20: "#f7f8fa",
  color21: "#eaeaea",
  color22: "#eaeaea",
  color25: "#FF7159",
  color26: "#4AD8FA",
  color27: "#f7f8fa",
  color28: "#4E8408",
  color29: "#79BC31",
  color30: "#E55E92",
  color31: "#FF1D25",
  color32: "#7bbb33",
  color33: "#fe15b8d",
  color34: "#EE0000",
  color38: "#E3E4E5",
  color39: "#F3F5F6",
  color40: "#333333"

5.4 KiB Raw Permalink Blame History Unescape Escape

AGENTS.md

项目目标

协作原则

文件与代码规范

主题与组件约定

小程序设计适配约定

修改边界

AppID 与发布相关

文档要求

原始设计色板参考

5.4 KiB

Raw Permalink Blame History