AGENTS.md

本文件用于约束在 Loan/client 仓库内工作的 AI agent / 协作者，目标是让改动更稳、更贴近当前项目结构，并减少无关返工。仓库信息变化后，请同步更新此文件。

项目概览

项目名称：Loan Assistant / 借贷助手 客户端
技术栈：Expo 55、React Native 0.83、React 19、TypeScript、expo-router、NativeWind 4、@ant-design/react-native 5
目标平台：iOS、Android、Web
包管理器：仓库包含 pnpm-lock.yaml，默认优先使用 pnpm
当前 UI 基调：浅色主题，根布局与全局 Provider 在 src/app/_layout.tsx

常用命令

安装依赖：pnpm install
启动开发环境：pnpm start
启动 Android：pnpm android
启动 iOS：pnpm ios
启动 Web：pnpm web
代码检查：pnpm lint

如果必须使用 npm，请确保不要混乱提交锁文件；默认仍以 pnpm-lock.yaml 为准。

目录约定

src/app：expo-router 路由入口、layout、页面级 screen 文件
src/app/(tabs)：底部标签页相关路由
src/components：跨页面复用组件
src/components/ui：更基础的 UI 组件与页面积木
src/hooks：自定义 hooks
src/utils：基础能力与业务支撑工具，例如 api、auth、storage
src/constants：主题和常量
src/global.css：NativeWind 全局样式入口
assets：运行时资源
design：设计参考稿或静态参考资料，默认不作为运行时代码来源
docs/antd：本地 Ant Design RN 参考文档，新增或调整组件时优先查阅
android、ios：原生工程，除非是原生能力、权限、构建配置相关改动，否则不要随意修改
dist：构建产物目录，不要手工编辑

代码组织规则

路由文件尽量保持轻量，复杂 UI 和业务逻辑优先下沉到 src/components、src/hooks、src/utils
本项目已配置路径别名：
- @/* -> src/*
- @/assets/* -> assets/*
新页面优先放在 src/app 下对应路由位置，不要回退到旧式集中路由表
涉及标签页结构时，同时检查 src/app/(tabs)/_layout.tsx
平台差异优先通过 *.web.tsx 等平台文件处理，避免在单文件里堆过多平台分支
尽量复用已有基础组件，不要在页面里重复造按钮、输入框、弹窗、状态标签

UI 与样式约定

样式方案以 NativeWind + global.css + tailwind.config.js 为主
组件型交互优先复用 @ant-design/react-native
根节点已经包裹 @ant-design/react-native 的 Provider，全局 Provider 变更集中放在 src/app/_layout.tsx
项目已有一套 Tailwind 扩展颜色和圆角 token，新增样式优先复用，不要到处散落魔法值
如果引入新的 Ant Design RN 组件，先查 docs/antd/llms-semantic.md 或 docs/antd/llms-full.txt
Web 与 Native 表现如果需要分流，优先延续现有 component.tsx / component.web.tsx 结构

数据、认证与存储

网络请求优先复用 src/utils/api.ts 中的统一请求封装，不要重复创建新的 axios client
接口地址与版本信息优先从现有配置读取，不要在页面或组件中硬编码 base URL
鉴权上下文在 src/utils/auth.tsx，修改登录态逻辑时同步检查 Provider、hook、请求头注入
本地持久化与缓存使用 src/utils/storage.ts 中的 MMKV 封装，避免绕过统一入口

工程约定

TypeScript 处于 strict 模式，新增代码不要用 any 糊过去，必要时补充明确类型
expo-router 已启用 typedRoutes，新增路由时保持类型友好
项目开启了 reactCompiler，默认不要为了“优化”到处添加 useMemo / useCallback
JS 层改动默认不要动 android/、ios/
配置类文件如 app.json、babel.config.js、metro.config.js、tailwind.config.js 修改前先确认影响范围
不要引入重量级新依赖，除非现有方案明显无法满足需求

Agent 工作方式

开始前先看 git status --short，确认工作区是否已有用户未提交改动
不要回滚与当前任务无关的变更
先阅读相关文件，再改代码；避免“按印象重写”
优先做最小必要改动，保持与现有风格一致
修改公共能力时，检查调用方是否需要同步更新
如果改动影响路由、鉴权、全局 Provider、主题或构建配置，在说明中明确指出

验证要求

最低要求：执行 pnpm lint
如果改动影响页面交互、路由、平台差异或构建配置，尽量补充对应平台验证
如果因为环境限制无法完成验证，需要在最终说明中明确写出“未验证项”

提交说明建议

最终汇报建议至少包含以下信息：

改了什么
为什么这么改
怎么验证
还有哪些风险或待补充项

待项目负责人补充