🐱 KnowMeow 诺喵

拍视频，读懂猫咪的每一刻
Know Meow, Know More.

KnowMeow（诺喵）是一个猫咪行为观察应用，通过上传猫咪短视频或照片，自动分析品种、行为、声音，输出行为解读和健康建议。支持宠物档案管理和成长日志时间轴。

项目采用本地优先 + 云端增强架构：

┌─────────────────────────────────────────────┐
│            微信小程序（独立运行）              │
│  miniprogram/                               │
│  ┌─────────────┐  ┌──────────────────────┐  │
│  │ 本地存储     │  │  云端 AI（cogvlm）   │  │
│  │ 宠物/记录    │  │  品种/行为/声音识别   │  │
│  │ wx.Storage  │  │  + GLM 文本解读       │  │
│  └─────────────┘  └──────────────────────┘  │
│  ┌──────────────────────────────────────┐   │
│  │ 云函数 uploadAnalyze                  │   │
│  │ → cogvlm 视觉 + glm-4.5-flash 文本 │   │
│  │ → Mock 降级（未配置云环境）         │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘

微信小程序（miniprogram/）— 当前主要开发方向，原生框架 + Vant Weapp，云开发模式（cogvlm AI + Mock 降级）
Web 前端（frontend/）— 已完成 v0.2.0 全部功能，进入维护状态
后端（backend/）— 仅供 Web 前端使用，小程序不需要

功能概览

模块	功能	状态
品种识别	识别猫咪品种（娱乐性质，10 种常见品种）	✅ cogvlm AI
行为分析	识别 15 种行为（正常/异常分类）	✅ cogvlm AI
声音分类	识别 8 种猫叫声（仅视频）	✅ cogvlm AI
照片分析	支持照片上传，跳过声音分析	✅ v0.2.0
行为解读	基于行为+声音生成自然语言解读	✅ AI + 规则引擎
纵向对比	对比过去 7 天记录，发现行为/声音变化	✅ v0.2.0
健康自查	引导用户完成健康自查清单（8 项）	✅
紧急程度	绿/黄/红三级指示 + 建议文字	✅ 评分制
用户认证	注册/登录，JWT Token 管理	✅ v0.2.0
宠物管理	创建宠物档案，保存分析记录	✅ v0.2.0
成长日志	按时间倒序的时间轴，缩略图+备注预览	✅ v0.3.2
记录详情	缩略图大图预览、备注、删除记录	✅ v0.3.2
保存记录	分析后一键保存到成长日志（含缩略图+备注）	✅ v0.3.2
保存后选项	保存后留在当前页，可选"分享日志"或"查看日志"	✅ v0.3.4
记录删除	成长日志支持按条删除记录（带确认对话框）	✅ v0.3.4
JSON 导入导出	成长日志支持 JSON 格式导入导出，数据零丢失	✅ v0.3.4
分享观察日志	一键生成图片保存到相册（去掉二级菜单）	✅ v0.3.4
视频缩略图	利用 wx.chooseMedia 自动获取视频封面	✅ v0.3.3
首次引导	使用指南可折叠卡片，首次访问默认展开	✅ v0.3.4
全量导出	导出全部成长日志为 JSON 文件	✅ v0.3.4
单元测试	Jest 测试框架，87 个用例覆盖规则引擎+存储+回归	✅ v0.3.12
年度回顾	1080x1080 统计卡片，支持下载	✅ v0.2.0
PDF 导出	生成可分享的观察日志图片	✅ canvas
访客限制	未登录每日 3 次免费分析	✅ v0.2.0
UI 精简	结果页标题动态化、保存区精简、分享图标同行	✅ v0.3.6
界面重构	WXML 模板表达式规范化、时区修复、照片选择降级、缩略图校验	✅ v0.3.9
代码加固	调试日志条件化、存储容量监控、回归测试套件(71 cases)	✅ v0.3.10
云开发接入	微信云开发环境配置、cogvlm AI 分析、.strip() bug 修复	✅ v0.3.11
AI 解读增强	glm-4.5-flash 生成个性化行为解读，降级规则引擎	✅ v0.3.12
视频分析修复	视频帧提取（snapshot→extractFrame→thumb→mock）、超时兜底	✅ v0.3.12
智能引导	使用指南根据用户操作状态动态高亮当前步骤	✅ v0.3.6
架构优化	常量统一管理、重复代码提取、timer/globalData 泄漏修复	✅ v0.3.5
数据迁移	localStorage 版本迁移机制（V1→V2 自动补全字段）	✅ v0.3.5
拍摄建议	可折叠拍摄技巧（视频 5 条 / 照片 4 条）	✅ v0.2.0
视频预检	亮度/模糊/时长自动检测	✅ OpenCV
微信小程序	原生小程序，8 页面 8 组件	✅ v0.3.0-mini
微信登录	wx.login → openid → JWT	✅ v0.3.0-mini
平台抽象层	platform/ 模块隔离平台依赖	✅ v0.3.0-mini

快速开始

环境要求

微信开发者工具（下载）
Node.js 18+（仅构建 npm 时需要）

启动小程序

cd miniprogram
npm install

运行单元测试

cd miniprogram
npx jest --verbose

然后在微信开发者工具中：

导入 miniprogram/ 目录，AppID: wxfdfebe0e999bfce6
工具 → 构建 npm（生成 miniprogram_npm/）
点击"编译"即可运行
云开发需配置：环境 ID cloud1-6ghtv69ccfa88fee + 环境变量 ZHIPU_API_KEY

小程序使用微信云开发，云函数 uploadAnalyze 调用智谱 cogvlm（视觉）+ glm-4.5-flash（文本解读）进行 AI 分析。未配置云环境时自动降级为 Mock 模式。视频分析需真机测试（模拟器不支持帧提取）。

Web 前端（可选，已进入维护状态）

cd frontend
npm install
npm run dev

打开 http://localhost:3000

项目结构

KnowMeow/
├── miniprogram/                     # ★ 微信小程序（主要开发方向）
│   ├── app.js                        # 小程序入口（wx.cloud.init）
│   ├── app.json                      # 全局配置（8 pages + tabBar）
│   ├── app.wxss                      # 全局样式（品牌色变量）
│   ├── project.config.json           # 项目配置
│   ├── platform/                     # 平台抽象层（PWA 迁移准备）
│   │   ├── storage.js               # 存储抽象 → wx.setStorageSync
│   │   ├── request.js               # 网络请求抽象 → wx.request
│   │   ├── login.js                 # 登录抽象 → wx.login
│   │   └── chooseMedia.js           # 媒体选择抽象 → wx.chooseMedia（含 wx.chooseImage 降级）
│   ├── utils/                        # 业务工具
│   │   ├── constants.js            # 业务常量统一管理
│   │   ├── localStorage.js          # 宠物/记录 CRUD（100条/宠物，缩略图管理）
│   │   ├── rules.js                 # 规则引擎（评分+解读+自查）
│   │   ├── mock-ai.js               # Mock AI 数据（10 品种/15 行为/8 声音）
│   │   ├── analyze.js               # 分析调度器（mock/云端切换）
│   │   ├── longitudinal.js          # 纵向对比（前端计算）
│   │   ├── request.js               # HTTP 封装（Web 前端用）
│   │   └── storage.js               # 存储/访客限制封装
│   ├── cloudfunctions/               # 云函数（可选，接真实 AI）
│   │   └── uploadAnalyze/           # AI 分析云函数（cogvlm 视觉 + GLM 文本解读）
│   ├── components/                   # 8 个可复用组件
│   │   ├── shooting-tips/           # 拍摄建议（折叠）
│   │   ├── breed-card/              # 品种卡片
│   │   ├── behavior-tags/           # 行为+声音标签
│   │   ├── urgency-indicator/       # 紧急程度指示灯
│   │   ├── health-checklist/        # 健康自查清单
│   │   ├── longitudinal-bar/         # 纵向对比信息条
│   │   ├── conversion-banner/       # 访客转化横幅
│   │   └── pdf-export/              # 分享观察日志（生成图片）
│   ├── pages/                        # 8 个页面
│   │   ├── index/                   # 首页（上传入口）
│   │   ├── result/                  # 分析结果页
│   │   ├── pet-list/                # 宠物列表页
│   │   ├── pet-detail/              # 宠物详情页（历史记录）
│   │   ├── record-detail/           # 单条记录详情页
│   │   ├── year-review/             # 年度回顾页
│   │   ├── user/                    # 用户中心页
│   │   └── login/                   # 登录页
│   ├── images/                       # TabBar 图标
│   └── miniprogram_npm/              # Vant Weapp（构建产物）
├── backend/                         # 后端（小程序和 Web 共用）
│   ├── main.py                      # FastAPI 入口，所有 API 端点
│   ├── database.py                  # SQLite 数据库（users/pets/records）
│   ├── auth.py                      # JWT 认证 + 微信登录
│   ├── knowmeow.db                  # SQLite 数据库文件（运行时生成）
│   ├── inference/
│   │   ├── __init__.py              # analyze_media() 统一分析管道
│   │   ├── models.py                # Pydantic 请求/响应模型
│   │   ├── breed.py                 # 品种识别（mock/真实双模式）
│   │   ├── behavior.py              # 行为识别（mock/真实双模式）
│   │   ├── sound.py                 # 声音分类（mock/真实双模式）
│   │   ├── quality.py               # 视频质量预检（亮度+模糊+时长）
│   │   └── rules.py                 # 规则引擎（紧急程度评分+解读模板）
│   ├── requirements.txt
│   └── temp/                        # 临时文件存储（处理后自动删除）
├── frontend/                        # Web 前端（已进入维护状态）
│   ├── index.html
│   ├── vite.config.js               # Vite + React + TailwindCSS v4 + API proxy
│   ├── package.json
│   └── src/
│       ├── main.jsx
│       ├── App.jsx
│       ├── index.css
│       ├── components/
│       └── utils/
└── docs/
    ├── PRD.md                       # 产品需求文档
    └── TESTING.md                   # 测试文档

平台抽象层

miniprogram/platform/ 目录将所有平台相关的 API 调用与业务逻辑隔离。未来迁移到 PWA 时，只需替换 platform/ 下的 4 个文件。

文件	方法	当前实现	PWA 替换方案
`storage.js`	`setItem`, `getItem`, `removeItem`, `clear`	`wx.setStorageSync`	`localStorage`
`request.js`	`request(config)`, `uploadFile(config)`	`wx.request`, `wx.uploadFile`	`fetch`, `FormData`
`login.js`	`login()`, `getUserProfile(desc)`	`wx.login`, `wx.getUserProfile`	OAuth2.0 流程
`chooseMedia.js`	`choosePhoto()`, `chooseVideo()`	`wx.chooseMedia`（照片降级 `wx.chooseImage`）	`<input type="file">`

保留的 wx.* 调用（UI/导航/Canvas 等）已标注 // TODO: PWA，共计 50 处。

API 文档

认证端点

POST `/api/auth/register`

用户注册。

Request: application/json

{ "username": "catlover", "password": "1234" }

Response 200

{ "token": "eyJ...", "user_id": 1, "username": "catlover" }

Error: 409 用户名已存在

POST `/api/auth/login`

用户名密码登录。

POST `/api/auth/wechat`

微信小程序登录。

Request: application/json

{ "code": "wx_login_code" }

Response 200: 同 login/register 格式。

Error: 400 INVALID_CODE 或 WECHAT_LOGIN_FAILED

所有需认证的端点在 Header 中携带 Authorization: Bearer <token>

分析端点

POST `/api/analyze`

上传照片或视频进行分析。

Request: multipart/form-data

Field	Type	Required	Description
media	File	Yes	视频(MP4/MOV ≤50MB ≤30s) 或照片(JPG/PNG/WebP ≤50MB)
media_type	String	No	`"video"`(默认) 或 `"photo"`
checklist	String	No	JSON 数组
pet_id	String	No	宠物 ID（登录用户可保存记录）

Response 200

{
  "session_id": "uuid",
  "media_type": "video",
  "record_id": 1,
  "longitudinal_insight": "...",
  "breed": { "id": "...", "name_zh": "英国短毛猫", "name_en": "British Shorthair", "confidence": 0.87, "description": "..." },
  "behaviors": [{ "id": "grooming", "label_zh": "舔毛理毛", "label_en": "Grooming", "confidence": 0.92 }],
  "sounds": [{ "id": "purring", "label_zh": "呼噜声", "label_en": "Purring", "confidence": 0.95 }],
  "interpretation": { "summary": "...", "advice": [{ "text": "...", "priority": "info" }] },
  "urgency": { "level": "green", "label": "状态良好", "message": "..." },
  "checklist": [{ "id": "appetite", "label": "食欲下降", "relevant": false, "note": "" }]
}

POST `/api/reanalyze`

基于自查清单重新分析（复用缓存，无需重新上传）。

宠物管理端点（需认证）

GET `/api/pets`

获取当前用户的所有宠物列表。

POST `/api/pets`

创建新宠物。

GET `/api/pets/{pet_id}/records`

获取宠物的历史分析记录。

GET `/api/pets/{pet_id}/year_review?year=2026`

获取宠物的年度统计回顾。

其他端点

GET `/api/health`

{ "status": "ok", "version": "0.2.0" }

GET `/api/checklist-items`

返回 8 项健康自查清单。

数据库结构

users          → id, username, password_hash, openid, created_at
pets           → id, user_id, name, created_at
records        → id, pet_id, user_id, session_id, media_type,
                 breed_data(JSON), behaviors(JSON), sounds(JSON),
                 interpretation(JSON), urgency_level,
                 checklist_selected(JSON), checklist_results(JSON),
                 created_at

环境变量

Variable	Default	Description
`KNOWMEOW_USE_MOCK`	`true`	`true`=mock 数据，`false`=真实模型（小程序通过 `useCloudAI` 控制，默认 `true` 已启用云模式）
`WECHAT_APPID`	—	微信小程序 AppID（小程序登录必需）
`WECHAT_SECRET`	—	微信小程序 AppSecret（小程序登录必需）

切换真实模型

export KNOWMEOW_USE_MOCK=false
pip install timm torch
实现各模块的 _real_*() 函数：
- backend/inference/breed.py → _real_detect(video_path)
- backend/inference/behavior.py → _real_recognize(video_path)
- backend/inference/sound.py → _real_classify(video_path)

技术栈

层	技术	状态
小程序	原生微信小程序 (wxml/wxss/js/json)	主要开发
小程序 UI	Vant Weapp	主要开发
平台抽象	自定义 platform/ 模块	主要开发
后端框架	Python 3.11 + FastAPI 0.135 + uvicorn	稳定
数据库	SQLite（内置，无需额外安装）	稳定
认证	PyJWT（HMAC-SHA256 签名，7 天有效期）	稳定
Web 前端	React 19 + Vite 6	维护
样式	TailwindCSS v4	维护
PDF 生成	jsPDF + html2canvas	维护
HTTP 客户端	axios	维护
视频处理	OpenCV 4.13	稳定
AI 推理（预留）	timm + PyTorch + moviepy + librosa	待开发

免责声明

KnowMeow 的分析结果仅供参考和娱乐用途，不构成任何兽医诊断或医疗建议。严禁推荐任何药物、剂量、治疗方案。如猫咪出现严重异常，请及时联系专业兽医。

最后更新: 2026-04-09

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
backend		backend
docs		docs
frontend		frontend
miniprogram		miniprogram
.gitignore		.gitignore
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

🐱 KnowMeow 诺喵

功能概览

快速开始

环境要求

启动小程序

运行单元测试

Web 前端（可选，已进入维护状态）

项目结构

平台抽象层

API 文档

认证端点

POST /api/auth/register

POST /api/auth/login

POST /api/auth/wechat

分析端点

POST /api/analyze

POST /api/reanalyze

宠物管理端点（需认证）

GET /api/pets

POST /api/pets

GET /api/pets/{pet_id}/records

GET /api/pets/{pet_id}/year_review?year=2026

其他端点

GET /api/health

GET /api/checklist-items

数据库结构

环境变量

切换真实模型

技术栈

免责声明

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

POST `/api/auth/register`

POST `/api/auth/login`

POST `/api/auth/wechat`

POST `/api/analyze`

POST `/api/reanalyze`

GET `/api/pets`

POST `/api/pets`

GET `/api/pets/{pet_id}/records`

GET `/api/pets/{pet_id}/year_review?year=2026`

GET `/api/health`

GET `/api/checklist-items`

Packages