# AGENTS.md

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

## 项目目标

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

- 保持项目结构简单、易懂、易修改
- 使用 `Taro + React + TypeScript` 作为核心技术栈
- 所有说明尽量使用中文
- 在保证可运行的前提下，减少复杂依赖

## 协作原则

- 修改代码前，先阅读现有文件，避免无意义重构。
- 优先做小步修改，保持项目始终可运行。
- 已确认使用 `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/`，尤其是以下类型：
  - 按钮
  - 卡片
  - 底部导航
  - 列表项
  - 状态块
- 如果一个结构或样式在两个及以上页面/区域重复出现，优先抽成可复用组件，而不是复制粘贴。
- 组件设计尽量保持“样式可配置、职责单一、命名清晰”，避免做过度复杂的大而全组件。

## 修改边界

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

## 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"