she-eagle-home

雌鹰谷

面向独居人士的居家维修 AI 诊断 Web App：拍照 / 上传照片 / 描述问题 → AI（Agnes 2.5 Pro Alpha）先追问澄清 → 给出安全分步解决方案 → 同步推送相关教学图片与视频。

线上体验

秒哒静态托管（演示）：https://html.shiyichuang.com/view/dfa434744e

本仓库的 config.js 不含任何真实 API Key（安全考虑，不泄露到公开仓库）。fork 后请按下方「API 密钥」说明填入你自己的 key 再部署；或直接在地址后加 ?mock=1 体验演示模式（无需 key）。

核心流程

1. 拍照 / 相册选择 / 文字描述 提出问题。
2. AI 追问澄清：信息不足时最多追问 2 轮（每轮可点击「跳过追问，直接给方案」）。
3. 给出诊断：问题类别、严重度、安全提示、可操作的步骤、所需工具。
4. 教学图片：自动搜索并展示相关维修图片（点击可放大）。
5. 教学视频：按类别/关键词匹配本地视频库，点击卡片可播放（当前为占位示例位，替换 data/videos.json 的 url 即可接入真实视频）。

本地运行

npm install
# 填写 AGNES_API_KEY（项目已内置测试 key，但为了安全建议填自己的）
cp .env.example .env
npm start   # http://localhost:3000

本地启动时走 代理模式：前端 → Express /api/diagnose → Agnes，API Key 保存在服务端 .env，不会暴露到浏览器。

双模式说明

模式	触发条件	密钥位置	图片搜索
代理模式	本地 npm start 运行	服务端 .env	服务端抓取 Bing + Openverse
直连模式	静态部署、无本地服务	前端 js/config.js（填你自己的 key）	浏览器直调 Wikimedia Commons + Openverse

API 密钥（安全重要）

本仓库不包含任何真实 API Key。两种使用方式：

• 本地代理模式（推荐，key 不进浏览器）：cp .env.example .env，在 .env 填入 AGNES_API_KEY / GEMINI_API_KEY，npm start 走 Express 服务端读取，key 仅存于服务端 .env（已被 .gitignore 忽略）。
• 静态直连模式（部署到 EdgeOne 等）：浏览器直调 LLM 网关，需在 public/js/config.js 填入 key。把你的 key（如 sk-xxxx）做 base64 编码后填到 AGNES_API_KEY_B64 / GEMINI_API_KEY_B64 字段：

  echo -n 'sk-你的key' | base64
  

  直连模式下 key 会出现在前端代码中，仅适合自有部署；请勿把含真实 key 的 config.js 提交到公开仓库（本仓库已将 _B64 字段置空为占位符）。

语音识别（腾讯云一句话识别）的 TENCENT_SECRET_ID / TENCENT_SECRET_KEY 仅用于 EdgeOne 函数 functions/api/asr.js，请在 EdgeOne 控制台配置为项目环境变量，不写在代码里。

更新教学视频 / 图片

• 视频：编辑 public/data/videos.json，把 url 换成真实视频地址（相对路径或外链），无需改代码。
• 图片：AI 自动根据诊断结果搜索相关图片；如果搜索失败，会显示「去必应 / 百度搜相关图片」的兜底链接。

项目结构

├── server/index.js          # Express：静态托管 + /api/diagnose + /api/image-search 代理
├── public/                  # 纯静态前端，可独立部署到任意静态托管
│   ├── index.html           # 单页（idle/preview/diagnosing/clarify/result/error）
│   ├── css/style.css
│   ├── js/config.js         # API Key 占位符（部署前填入你自己的 key）
│   ├── js/{app,api,camera,images,render,settings,videos}.js
│   └── data/videos.json     # 分类视频库
├── scripts/
│   ├── mcp-raw.mjs          # 原生 SSE MCP 客户端（部署用）
│   └── deploy-miaoda.mjs    # 秒哒静态托管部署脚本
├── .env                     # AGNES_API_KEY（已加入 .gitignore）
├── .env.example
└── package.json

EdgeOne 部署（非大陆站点）

上传 edgeone-最新版部署文件夹/ 里的全部文件（含 index.html、js/、css/、data/、functions/、package.json）到 EdgeOne Pages 项目即可。

云端后端与存储（重要）

• 默认走云端真实后端：账号 / 会话 / 邀请链 / 悬赏社区（串巢）数据全部存 EdgeOne Blob 存储（命名空间 hrl，首次调用 /api/auth/* 或 /api/bounty/* 自动创建，无需在控制台手动绑定 KV）。
  • 依赖已在根目录 package.json 声明（@edgeone/pages-blob），EdgeOne Pages 构建时自动安装。
  • 前端开关由 public/js/config.js 的 APP_CONFIG.USE_REMOTE 控制。
• 演示模式：URL 加 ?mock=1 即回退到浏览器 localStorage 演示（无需后端，本地可回归测试）。
  • 验证码填 1234；首次登录填邀请码 MMX2026 + 勾选女性承诺
  • 管理员码 888888 免验证码/邀请码/承诺直接登录

语音识别配置

语音走腾讯云一句话识别（每月 5000 次免费），需在 EdgeOne 控制台为项目配置环境变量：

TENCENT_SECRET_ID=你的腾讯云 SecretId
TENCENT_SECRET_KEY=你的腾讯云 SecretKey

未配置时点击语音按钮会提示「语音识别未配置」，不影响文字输入。

部署到秒哒

NO_PROXY='*' node scripts/deploy-miaoda.mjs

脚本会递归打包 public/ 目录，通过 MCP 部署到秒哒静态托管，部署成功后返回预览链接。

注意：mcp-raw.mjs 使用原生 SSE + JSON-RPC 实现，绕过了官方 SDK 在代理环境下对长连接 SSE 的兼容问题。