Skip to content

AGENT.md

Latest commit

 

History

History
112 lines (80 loc) · 3.3 KB

AGENT.md

File metadata and controls

112 lines (80 loc) · 3.3 KB
Raw

AGENT.md

心景（Mindscape）项目协作说明。

项目定位

  • 这是一个基于 Taro 4 + React 18 + TypeScript 的微信小程序项目。
  • 产品核心是“在情绪景观中漫步、写下记忆、与他人的记忆产生共鸣”。
  • H5 主要用于本地开发调试，微信小程序端才连接真实云开发能力。

快速开始

npm install
npm run dev:h5
npm run dev:weapp
npm run lint

运行约定

  • H5 环境默认使用 Mock 数据，便于前端独立开发。
  • 小程序环境使用微信云开发，云环境配置在 src/config/env.ts。
  • 不要依赖运行时 process.env；当前项目通过 typeof wx 和编译期常量判断环境。

关键目录

src/
  components/    UI 组件，如创作面板、个人面板、教程弹层
  pages/         页面入口，当前核心页面是 `pages/index`
  stores/        Zustand 状态管理
  services/      云函数、广告、AI、社交等服务层
  core/          场景引擎、实体、渲染器、系统
  constants/     世界参数、情绪、天气、调色板
  utils/         数学、地形、性能、触觉等工具

cloud/
  memory/        记忆相关云函数
  interact/      共鸣、举报等互动云函数

核心数据流

  1. src/pages/index/index.tsx 负责游戏入口、欢迎页、教程、手势绑定。
  2. WorldCanvas 驱动场景渲染和世界移动。
  3. CreationPanel 创建记忆，调用 services/ai-service.ts。
  4. ai-service.ts 在 H5 下生成 mock 结果，在小程序端通过 memory 云函数落库。
  5. memory-store / world-store / user-store 负责前端状态同步。

开发时优先遵守的约束

环境判断

  • 不要写 process.env.TARO_ENV 之类的运行时代码。
  • 优先沿用 src/config/env.ts 中的判断逻辑。

Canvas 兼容

  • 微信小程序 Canvas API 能力弱于浏览器。
  • 避免直接依赖 ctx.roundRect() 等兼容性差的 API。
  • 绘制前后注意 save() / restore()，避免样式污染到其他图层。

样式单位

  • 小程序界面优先使用 rpx。
  • 修改样式时同时兼顾 H5 和微信开发者工具下的显示效果。

H5 与小程序差异

  • H5 无法直接验证云开发、广告和真实上传能力。
  • 涉及云函数、广告、登录、内容安全时，要明确区分 “mock 行为” 和 “真实行为”。

云函数约定

memory

  • create: 创建记忆
  • getByChunk: 按区块获取记忆
  • getByRange: 按范围获取记忆
  • getMine: 获取我的记忆
  • getMyResonances: 获取我的共鸣
  • delete: 删除记忆
  • checkSafety: 内容安全检查

interact

  • resonate: 共鸣
  • unresonate: 取消共鸣
  • check: 检查是否已共鸣
  • count: 获取共鸣数
  • report: 举报

文档与改动建议

  • 优先做小步修改，避免同时重写渲染层、状态层和服务层。
  • 改动交互时，至少检查：
    • 欢迎页是否还能进入主流程
    • 长按行走、上滑创作、下滑回溯是否正常
    • H5 mock 模式下是否还能加载初始记忆
  • 改动云函数参数时，同时更新前端调用和 cloud/README.md。

交付前检查

npm run lint

可选验证：

  • npm run dev:h5 检查基础 UI 和交互
  • npm run dev:weapp 在微信开发者工具中验证小程序兼容性