SouTan/win10-miniprogram-handoff
Watch
3
0
Fork
You've already forked win10-miniprogram-handoff
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
2 commits 1 branch 0 tags 233 KiB
  • Vue 49.4%
  • JavaScript 29.5%
  • Java 19.7%
  • SCSS 1.1%
  • HTML 0.3%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
liuser 8ad193efdb 更新记录
2026-09-16 17:07:48 +08:00
backend-reference init 2026-09-16 11:29:37 +08:00
hermes_chat_uniapp_api 更新记录 2026-09-16 17:07:48 +08:00
hermes_chat_uniapp_ui 更新记录 2026-09-16 17:07:48 +08:00
spa-reference init 2026-09-16 11:29:37 +08:00
README.md 更新记录 2026-09-16 17:07:48 +08:00
WIN11-更新说明.md 更新记录 2026-09-16 17:07:48 +08:00

README.md

Win10 小程序开发交接包（Cursor 直接使用）

本目录由 YuanZhou 仓库对话整理导出，供 Windows 10 Cursor 继续开发 hermes_chat_uniapp_*。
文中路径均为相对路径（相对本交接包或相对 monorepo 根），不含本机绝对路径。

Win11 端后续联调 / 体验版更新（必读）： 见同目录 WIN11-更新说明.md。
本包内 hermes_chat_uniapp_* 为较早源码快照；以 monorepo 根目录最新工程为准，不要用快照覆盖最新代码。

1. 本包目录结构

win10-miniprogram-handoff/
├── README.md                          ← 本文件（必读）
├── WIN11-更新说明.md                   ← Win11 联调后增量说明（无完整源码）
├── hermes_chat_uniapp_api/            ← 小程序 BFF 快照（可能落后于仓库）
├── hermes_chat_uniapp_ui/             ← uni-app Vue3 快照（可能落后于仓库）
├── spa-reference/                     ← Web SPA 关键实现（对齐功能时对照）
│   ├── api/                           dashboardAuth / dashboardAudio
│   ├── components/                    ChatMessageList / ChatComposer / SessionHistoryList
│   ├── utils/                         tuiGateway / assistantDisplay / attachFiles / holdToTalk
│   └── views/                         ChatView.vue（会话/流式/新建/删除核心）
└── backend-reference/                 ← 能碳侧角色→profile 与 handoff 参考 Java
    ├── HermesChatRoleSupport.java
    ├── HermesSpaController.java
    └── HermesSpaHandoffServiceImpl.java

在 Win10 上建议：直接在 YuanZhou monorepo 里打开最新的
hermes_chat_uniapp_api + hermes_chat_uniapp_ui；本包主要用于文档、SPA 参考与历史快照对照。

2. 产品目标（小程序）

项 约定
工程名 hermes_chat_uniapp_api（Spring Boot）、hermes_chat_uniapp_ui（uni-app Vue3）
功能对齐 先对齐 Web SPA（登录、profile、会话列表、发消息、流式、语音转写代理）
前端职责 只做页面；鉴权/Hermes HTTP 走 BFF；会话与流式走 TUI WebSocket（同 SPA）
数据库 暂无库；平台用户写在 application.yml 的 app.users
不走 Telegram Telegram/企微等是 Messaging Gateway「挂在对方 App」；小程序是自研 UI，应对齐 SPA 的 BFF + TUI

3. 架构与数据流（必懂）

3.1 两条 Hermes 通道（不要混）

通道 用途 小程序是否用
Messaging Gateway（Telegram / Weixin / 企微…） Hermes 当 bot 挂在第三方 IM 否（不是小程序架构）
TUI Gateway（Dashboard /api/ws + JSON-RPC） SPA / 大屏 / 小程序自研聊天壳 是（与 SPA 同协议）
OpenAI 兼容 /p/{profile}/v1/chat/completions 能碳旧 SSE BFF 小程序当前骨架未主用；管理端 SPA 已转 TUI

3.2 小程序登录与 Hermes 校验（BFF）

1) 用户在小程序输入账号密码
2) POST /api/auth/login
   - 查 app.users（YAML）：未命中 → 「用户未注册，请先注册」
   - 命中后按 hermes.* 代登 Dashboard（password-login）
   - 再调 /api/auth/me 校验 Dashboard 会话
   - 签发平台 token（内存 SessionStore），服务端保存 Hermes Cookie
3) 后续请求：Authorization: Bearer <token>
4) GET /api/hermes/profiles          → 代理 Dashboard profile 列表
5) POST /api/hermes/ws-handoff       → 返回 { wsUrl, ticket, ttlSeconds }
6) 小程序 uni.connectSocket(wsUrl?ticket=...) → TUI JSON-RPC
   - session.list / session.create / session.resume / session.delete
   - prompt.submit + 事件 message.delta / message.complete
7) POST /api/hermes/audio/transcribe → 语音转写代理（Cookie 在 BFF）

重要： hermes.dashboard-base-url 不要用会 HTTP→HTTPS 301 的 SPA 域名 :80。
BFF 代登应直连 Hermes 主机（如 hermes-prod... 或本机 Dashboard :9119）。
浏览器/小程序侧 WS 用 hermes.public-ws-url（须 wss，常经 SPA 同源 /__hermes/）。

3.3 能碳管理端嵌入 SPA（对照，非小程序本体）

  • 能碳登录后 iframe：VUE_APP_HERMES_CHAT_SPA_URL / VITE_HERMES_CHAT_SPA_URL
  • BFF：POST /business/hermes/spa/ws-handoff → ticket + lockedProfile + wsUrl
  • 角色 → profile（已定稿）：
能碳角色 Hermes profile
超级管理员 / role_key superadmin / admin / manager <项目名>-admin
其它普通用户 <项目名>-user
大屏 unicode handoff <项目名>-user（不是 admin）

参考实现：backend-reference/HermesChatRoleSupport.java
勿只用 SysUser.isAdmin()（若依常仅 userId=1），否则 manager 会错锁到 user。

中华六建已同步同类逻辑；管理端嵌的是远程 SPA 域名，气泡/结论过滤改的是 SPA 工程，需重新构建发布 SPA 才生效。

4. SPA 消息渲染逻辑（空白气泡 /「结论」）

复杂任务时 Hermes 会多次 message.delta / message.complete（工具轮、中间帧）。

4.1 旧问题

  • 空 delta / 无正文 complete 仍建「助手」气泡 → 堆空白框
  • 列表曾放行 streaming 空气泡

4.2 现行产品规则（已写入 SPA 参考代码）

界面只渲染从「结论」起的助手正文；中间过程一律不显示。

关键文件：

  • spa-reference/utils/assistantDisplay.js — extractConclusionContent / hasConclusionContent
  • spa-reference/views/ChatView.vue — 事件处理、rawContent vs content、prune
  • spa-reference/components/ChatMessageList.vue — visibleMessages 过滤

标记识别（节选）：结论、结论：、**结论**、# 结论、## 结论。

小程序应对齐同一展示规则（可直接移植 assistantDisplay.js）。

4.3 「新建」会话坑

删除会话后往往会自动补建 live session；「新建」若再走 ensureLiveSession 的 early-return（已有 sessionId 直接 return）会无反应。
SPA 已改为强制 session.close（若有）→ session.create。见 ChatView.vue 的 createNewSession。

5. 已落地的小程序工程说明

5.1 hermes_chat_uniapp_api（本包内完整源码）

  • Spring Boot 2.7，风格对齐能碳（R / 包结构），未整仓拷贝 qlcloud 多模块（避免强依赖库）
  • 端口默认 8088
  • 演示用户（application.yml）：demo/demo123、admin/admin123
  • 主要接口：
方法 路径 说明
POST /api/auth/login 平台用户 + Hermes 代登
POST /api/auth/logout 退出
GET /api/auth/me 平台用户信息
GET /api/hermes/profiles profiles
POST /api/hermes/ws-handoff wsUrl + ticket
POST /api/hermes/audio/transcribe 语音
GET /api/hermes/files/download?path= 文件

配置项前缀：app.users、hermes.dashboard-base-url、hermes.public-ws-url、hermes.dashboard-username/password 等。

启动（Win10）：

cd hermes_chat_uniapp_api
mvn spring-boot:run

5.2 hermes_chat_uniapp_ui（本包内完整源码）

  • uni-app Vue3 + Vite 模板改版
  • 页面：pages/login/login、pages/chat/chat
  • 环境变量：.env.development 中 VITE_API_BASE=http://127.0.0.1:8088
  • TUI 客户端：src/utils/tuiGateway.js（uni.connectSocket）
  • RPC：session.list / session.create / session.resume / prompt.submit

本地启动：

cd hermes_chat_uniapp_ui
npm install
npm run dev:h5

微信：

npm run dev:mp-weixin

用微信开发者工具打开：hermes_chat_uniapp_ui/dist/dev/mp-weixin，开发期勾选「不校验合法域名」。

5.3 小程序功能进度（已被 Win11 更新说明覆盖）

下列项在 monorepo 最新工程 中多数已完成，细节见 WIN11-更新说明.md：

  • 助手展示仅「结论」起
  • 附件上传（25MB，image.attach_bytes / file.attach）
  • 按住说话 UI + BFF 转写
  • Markdown / echarts（导出为图片进列表）
  • DeepSeek 风格 UI；侧栏 profile+刷新
  • 微信合法域名与体验版上传（代码质量已通过一轮）
  • 删除会话后强制「新建」是否与 SPA 完全一致（建议再对一下）

发体验版：npm run build:mp-weixin → 导入 dist/build/mp-weixin（勿用 dist/dev）。

6. SPA 参考要点速查

能力 参考文件
密码登录 / profiles / ws-ticket spa-reference/api/dashboardAuth.js
语音转写 spa-reference/api/dashboardAudio.js
WS JSON-RPC spa-reference/utils/tuiGateway.js
附件体积 25MB spa-reference/utils/attachFiles.js → MAX_ATTACH_BYTES
流式与会话 spa-reference/views/ChatView.vue
结论过滤展示 spa-reference/utils/assistantDisplay.js

常见 RPC：

  • session.list { profile, limit }
  • session.create { title, source: 'web', profile }
  • session.resume { session_id, profile }
  • session.close / session.delete
  • prompt.submit { session_id, text }
  • 事件：message.delta / message.complete / gateway.ready

发消息：prompt.submit（不是 chat.send）。

7. 给 Win10 Cursor 的执行提示（可直接粘贴）

你在开发 Hermes 小程序：后端 hermes_chat_uniapp_api，前端 hermes_chat_uniapp_ui。
功能对齐 Web SPA（本交接包 spa-reference），前端只做页面。

硬约束：
1) 平台用户在 application.yml 的 app.users，无数据库；未注册提示「用户未注册，请先注册」；登录后必须 Hermes Dashboard 代登校验。
2) 会话/流式走 TUI Gateway（ws-handoff 的 wss + ticket），不要用 Telegram Messaging 路径。
3) 助手气泡只展示从「结论」开始的内容；中间轮不展示（见 spa-reference/utils/assistantDisplay.js）。
4) 附件单文件上限 25MB（对齐 SPA）。
5) 修改时先读本包 README.md 与 spa-reference，再改 uniapp 工程。

当前优先：以 monorepo 最新 uniapp 工程为准；先读 WIN11-更新说明.md；剩余可对 SPA「删除后强制新建」、线上 nginx/frpc 与体验版真机回归。

8. 相关 monorepo 工程（在完整仓库中的相对路径）

若 Win10 克隆了完整 YuanZhou 仓库，除本交接包外还可对照：

相对路径 说明
hermes_chat_spa/ 正式 SPA 源码（生产发布对象）
hermes_chat_uniapp_api/ 小程序 BFF（以这里为准）
hermes_chat_uniapp_ui/ 小程序前端（以这里为准）
win10-miniprogram-handoff/WIN11-更新说明.md Win11 联调增量文档
yuanzhou_api/.../HermesChatRoleSupport.java 角色→profile
yuanzhou_api/.../HermesSpaHandoffServiceImpl.java SPA/大屏 handoff
yuanzhou_ui/.../agentChat/ 管理端 iframe 嵌 SPA
zhonghualiujian_*（若旁挂） 中华六建已嵌 SPA；角色映射已同步

9. 已知生产注意

  1. BFF dashboard-base-url 打到 SPA 域名 :80 会 301，代登失败；应打 Hermes/Dashboard HTTP 口。
  2. HTTPS 小程序/页面禁止 ws://，必须用 wss://.../__hermes/api/ws 一类配置。
  3. 中华六建嵌远程 SPA：改气泡逻辑后必须 重新发布 SPA 静态资源，只发能碳 jar 不够。
  4. SPA 单附件默认上限 25MB。
  5. 小程序公网 BFF 示例域名：https://uniappApi.bingjun360.com；socket：wss://spa.bingjun360.com。内网 nginx 示例见 WIN11-更新说明.md §7。

10. 版本与日期

  • 交接包初版整理：2026-09-16
  • Win11 增量文档：同日下午（联调 + 体验版上传后）→ WIN11-更新说明.md
  • 快照范围：初版导出的 uniapp 双工程 + SPA/能碳关键参考；功能以仓库最新提交为准
  • 本包用于 Win10 旁路启动上下文与文档，不替代 monorepo 源码