YGChatCS/AGENTS.md

YGChatCS 项目速览

本文档面向接手本仓库的 AI 编程助手。开始改代码前请先读这里，再按需深入具体文件。

项目定位

YGChatCS 是一个基于 uni-app + Vue 3 的多端应用，当前配置重点面向微信小程序。业务上以酒店/文旅场景的 AI 聊天助手为主，包含首页聊天、发现内容、商品/房型详情、订单、工单服务、快捷预订、WebView 桥接等模块。

技术栈

• 框架：uni-app 3、Vue 3、Vite 5、Tailwindcss。
• 状态管理：Pinia 3，使用 pinia-plugin-unistorage 做持久化。
• 图标：uni-icons、自定义图标znicons
• 样式：SCSS，公共工具类在 src/static/scss/，全局变量在 src/uni.scss。
• 多端：保留 H5、App、各类小程序脚本；当前微信小程序配置最完整。
• 组件生态：src/uni_modules/ 中包含 DCloud 插件和第三方插件，如 uni-popup、uni-icons、z-paging、zero-markdown-view。

自定义图标使用方式

<template>
    <uni-icons fontFamily="znicons" size="24" color="#6A717F">
        {{ zniconsMap["zn-camera"] }}
    </uni-icons>
</template>

<script>
import { zniconsMap } from "@/static/fonts/znicons.js";
</script>

常用命令

包管理器字段声明为 Yarn 1：

yarn install
yarn dev:mp-weixin
yarn build:mp-weixin
yarn switch-client zhinian

package-lock.json 和 yarn.lock 同时存在。除非任务明确要求，不要随意重生成或混改锁文件；优先遵循 package.json 的 packageManager。

关键入口

• src/main.js：创建 Vue/uni-app 应用，注册 Pinia；微信小程序环境注册 utils/share。
• src/App.vue：应用生命周期入口，onLaunch 会调用 getEvnUrl() 获取/设置服务地址，并调用 refreshToken() 刷新登录态。
• src/pages.json：页面与分包路由。主页面是 pages/index/index，分包包括 pages-order、pages-service、pages-quick、pages-booking、pages-bridge。
• src/manifest.json：uni-app 多端配置；微信小程序 appid、隐私权限、插件配置在这里。
• project.config.json：微信开发者工具项目配置，根级 appid 需要与 src/manifest.json 保持一致。
• vite.config.js：配置 @ 指向 src，启用 @dcloudio/vite-plugin-uni，并对构建资源名做 md5/hash 处理。

目录地图

• src/pages/：主包页面和聊天相关组件。pages/index/index.vue 是首页壳，组合聊天主列表、日历、更多服务和抽屉。
• src/pages/ChatMain/：聊天主体验，包括顶部导航、欢迎区、输入区、消息卡片、长回答页、通知消息等。
• src/pages/ChatModule/：AI 工具调用渲染模块，例如快捷预订、发现卡片、地图、活动、推荐内容、长答案、图片/商品卡等。
• src/pages/Discovery/：发现页内容流和快捷问题。
• src/pages/goods/：商品/房型详情、相册、套餐、设施、日期选择和确认组件。
• src/pages-order/：订单列表、订单详情及订单卡片、二维码、状态、用户信息等组件。
• src/pages-service/：服务/工单订单列表。
• src/pages-quick/：快捷入口列表及卡片。
• src/pages-booking/：预订页面。
• src/pages-bridge/：上传图片、保存图片等桥接页面。
• src/pages/webview/：内嵌 WebView 页面及桥接脚本，src/router/index.js 会把外部 URL 包装到这里。
• src/components/：跨页面通用组件，如 TopNavBar、Calender、ImageSwiper、TagsGroup、Stepper、CreateServiceOrder、Feedback 等。
• src/request/：请求封装和 API 分组。
• src/store/：Pinia store，模块包括 app、location、picture、selectedDate。
• src/constant/：客户端配置、token key、事件常量、业务类型常量。
• src/utils/：WebSocket、流式/打字机、URL 参数、分享、更新等工具。
• scripts/：客户配置切换脚本。

请求、环境与登录

• src/request/base/request.js 是统一请求封装。相对 URL 会拼接 useAppStore().serverConfig.baseUrl，请求头会带 clientId、token 和位置信息。
• src/request/base/baseUrl.js 定义生产/测试 HTTP 和 WSS 地址。
• src/request/base/config.js 控制环境地址。developVersion = true 时直接使用测试地址；发布前需关注 versionValue 和 developVersion。
• src/request/api/ 按业务拆分 API：登录、主页面数据、会话、商品、订单、工单、反馈、服务地址、文件上传、AI 流式接口等。
• 登录与 token 逻辑在 src/hooks/useGoLogin.js、src/manager/LoginManager.js、src/constant/token.js。token key 会按当前客户端类型隔离。
• HTTP 返回 424 时请求层会移除 token、发出登出事件，并跳转登录。

AI 聊天与实时通信

• 主聊天列表在 src/pages/ChatMain/ChatMainList/index.vue，文件较大，是聊天状态、消息渲染、WebSocket 初始化和发送的核心。
• src/utils/WebSocketManager.js 是跨端 WebSocket 管理器，负责连接、重连、队列、发送和销毁。
• src/request/api/AgentChatStream.js 是微信小程序端的分块/流式请求封装，使用 uni.request({ enableChunked: true }) 解析 SSE 风格数据；也提供 stopAbortTask() 终止当前请求。
• AI 返回的 toolCall.componentName 会在聊天列表中映射到 ChatModule 或通用组件。新增工具卡片时，通常需要同时改组件、渲染分支和数据结构处理。

多客户端配置

根目录 client-configs.json 保存多客户端配置：zhinian、nianhelper、duohua、tianmu。当前 src/constant/base.js 的 getCurrentConfig() 返回 CLIENT_CONFIGS.zhinian。

切换客户配置请使用：

yarn switch-client <client-name>

脚本 scripts/update-appid.js 会更新：

• src/constant/base.js 的当前客户端。
• src/manifest.json 的 mp-weixin.appid。
• project.config.json 的根级 appid。
• src/uni.scss 的主题色变量。

改配置时要保证这些文件同步，尤其是微信小程序 appid 与主题色。

样式约定

• .editorconfig 要求 2 空格、LF、UTF-8、去尾随空格；Markdown 不强制去尾随空格且不强制最终换行。
• 公共 SCSS 工具类集中在 src/static/scss/index.scss 及其拆分文件，很多页面依赖 flex-*、w-*、h-*、px-* 等类。
• 主题色变量在 src/uni.scss，会被 switch-client 自动改写。不要手工改一处忘记同步配置。
• 页面基本使用 navigationStyle: "custom"，导航栏通常由自定义组件实现。

编码与文本注意事项

当前终端读取部分中文注释、README 和字符串时显示为乱码，但项目文件声明为 UTF-8。修改这些文件时：

• 不要因为显示乱码就大面积重写注释或中文文案。
• 尽量只改任务相关代码块。
• 涉及中文展示文案时，在编辑器中确认真实编码和页面效果。

开发注意事项

• 优先使用 @/ 别名引入 src 下模块。
• 不要直接改 dist/，它是构建产物。
• 不要随意改 src/uni_modules/ 中第三方插件源码，除非任务就是修补插件行为。
• 新增页面必须同步 src/pages.json；新增分包页面要放入对应 subPackages。
• 需要持久化的全局状态优先放在 Pinia store，并按现有模块风格使用 unistorage: true。
• 网络请求优先新增到 src/request/api/，复用 src/request/base/request.js，不要在页面里散落裸 uni.request，流式/分块场景除外。
• 跳转外部 H5 优先使用 src/router/index.js 的 WebView 包装方式。
• 需要登录态的交互参考 checkToken()、goLogin() 和现有事件常量。

验证建议

仓库当前没有明确的测试脚本。完成修改后至少做对应平台构建或运行：

yarn build:mp-weixin

如果只改 H5 可补充：

yarn build:h5

涉及客户切换时，运行 yarn switch-client <client-name> 后检查 src/manifest.json、project.config.json、src/constant/base.js、src/uni.scss 的同步变化。