Files

T

john 14a00774d9 feat(h5): web 联网能力、实时查询路由与 session Finish 对齐

- 新增 web 能力并挂载 platform/web（web_search/fetch_url）
- 实时查询强制 web skill，router fallback 与 await session Finish
- Session Broker 覆盖率/指标、stream replay 与相关单测/E2E 脚本

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-06 16:06:26 +08:00

5.5 KiB

Raw Blame History

本地开发

这是本机本地开发文档，只处理当前工作区里的源码联调，不做任何生产同步。
pnpm dev 不再启动 Plaza；如果需要联动 Plaza，请显式运行 pnpm dev:all，或者单独运行 pnpm dev:plaza / pnpm start:plaza。
Plaza 专用脚本的源码默认指向同级仓库 ../memind_plaza；如你的目录不同，请用 PLAZA_APP_DIR 覆盖。
生产 / 测试 / 预览隔离仍单独看生产 / 测试 / 预览隔离规程。

pnpm dev 启动后，用 127.0.0.1 + 端口 访问本仓库自己的服务：

服务	地址
MindSpace H5	http://127.0.0.1:5173/?preview=mindspace
Ops 审核后台	http://127.0.0.1:3002/ops/
API / Portal	http://127.0.0.1:8081
memind_adm	http://127.0.0.1:8082
Plaza	http://127.0.0.1:3001/plaza

pnpm install
cp .env.example .env
pnpm dev
pnpm open:local-test   # 浏览器打开 H5

LaunchAgent 常驻（推荐本机联调）

终端里跑 pnpm dev 会在 Cursor / 终端关闭时被 SIGTERM 停掉。若希望登录后自动拉起、掉线自恢复，可安装 LaunchAgent（与 imgproxy / goosed 同类）：

pnpm setup:dev-launchagent
# 卸载
pnpm setup:dev-launchagent:uninstall

项	值
Label	`cn.tkmind.memind-dev`
进程	portal (8081) + memind_adm (8082) + Ops (3002) + Vite (5173)
日志	`~/Library/Logs/memind-dev.log`

安装后仍可用 pnpm dev 做前台调试；两者不要同时占用同一端口。重启服务：

launchctl kickstart -k gui/$(id -u)/cn.tkmind.memind-dev

需要旧式全栈联动时，改用：

pnpm dev:all

环境变量

变量	默认	说明
`H5_PORT`	8081	Portal / API
`VITE_PORT`	5173	MindSpace 前端
`PLAZA_PORT`	3001	Plaza
`OPS_PORT`	3002	Ops SPA
`ADMIN_PORT`	8082	memind_adm
`H5_PUBLIC_BASE_URL`	http://127.0.0.1:5173	公开链接基址
`PLAZA_APP_DIR`	../memind_plaza	Plaza 专用脚本的源码路径（`pnpm dev:plaza` / `pnpm start:plaza` / `pnpm dev:all`）
`MEMIND_SESSION_BROKER_ENABLED`	`0`（未设置）	Session Broker 灰度开关；Patch 2+ 本地验证时可设 `1`，见 H5 Session 架构

H5 Session 架构本地全量联调（`0706-bug干净` 分支）

在 本机 .env（勿提交 Git）打开下列开关后重启 pnpm dev：

MEMIND_SESSION_BROKER_ENABLED=1
MEMIND_ROUTER_NORMALIZED_DECISION=1
MEMIND_SSE_EVENT_TAXONOMY=1
MEMIND_RUN_STREAM_REPLAY=1
MEMIND_H5_HTML_FINISH_GUARD=1

开关	验证点
`MEMIND_SESSION_BROKER_ENABLED`	Portal 启动日志、`sessionAccess` 路径
`MEMIND_SESSION_BROKER_METRICS`	`[session_broker.*]` structured log（§13.4）
`MEMIND_ROUTER_NORMALIZED_DECISION`	gateway 读 `decision.route` / `session_hint`；`shadow` 仅打 `[router-shadow]` 日志
`MEMIND_SSE_EVENT_TAXONOMY`	SSE payload 多 `taxonomy` 字段
`MEMIND_RUN_STREAM_REPLAY`	run SSE 含 `id:`，断线重连补发
`MEMIND_SESSION_STREAM_REPLAY`	session SSE 持久化 + Last-Event-ID 重连补发（4c）
`MEMIND_H5_HTML_FINISH_GUARD`	Finish 后假交付检测 / 自动 repair

启动后应看到类似：

[Portal] H5 session flags: MEMIND_SESSION_BROKER_ENABLED, ...

回归：

npm run verify:h5-session-patches
# 内含：单测、§5.7 session broker coverage、goosed proxy boundary、MindSpace publish guards

手工 soak 清单（全量开发完成后执行）：pending-fixes/h5-local-soak-20260706.md

关闭某项：对应变量改 0 或删除后重启 dev。

Plaza 本地开发说明见 plaza-local.md。生产发布、同步与回滚不要在这里处理，统一看生产更新发布指南。

本地 `.env` 与 103 生产 `.env` 分离

项	本地（本机 `.env` / `../../.env.local`）	103 生产（服务器 `/Users/john/Project/Memind/.env`）
配置真相	复制 `.env.example`，只填本地联调值	仅在 103 维护，不提交 Git
`TKMIND_API_TARGET`	通常单实例 `https://127.0.0.1:18006`	多 goosed 实例，见 103 runtime topology
`H5_PUBLIC_BASE_URL`	`http://127.0.0.1:5173`	`https://mm.tkmind.cn`
`MEMIND_SESSION_BROKER_ENABLED`	Patch 2 起可本地设 `1` 验证	灰度窗口由运维在 103 `.env` 单独开启
RDS / Redis	可连本地 MySQL 或留空	生产 RDS + Redis，见 103 `.env`

硬规则：不要把 103 的 .env、密钥、RDS 连接串复制进仓库；.env.example 只记录变量名与本地示例值。

公众号 Agent 调试

服务号消息转发到专属 Agent 这条链路默认关闭，只有显式设置下面这些变量后才会启用：

H5_WECHAT_MP_ENABLED=1
H5_WECHAT_MP_APP_ID
H5_WECHAT_MP_APP_SECRET
H5_WECHAT_MP_TOKEN

服务号后台需要把服务器地址指向：

{H5_PUBLIC_BASE_URL}/webhooks/wechat-mp/messages

当前版本只支持“明文模式”回调，不支持 aes 安全模式解密。要保证 H5 微信 OAuth 和公众号消息使用同一个服务号 AppID，这样消息里的 openid 才能直接命中已绑定用户。

如果要立即停用这版，不改代码也可以先把：

H5_WECHAT_MP_ENABLED=0

然后重启 server.mjs。这相当于运行时止血；如果确认整版不要，再按代码回撤处理。

5.5 KiB Raw Blame History Unescape Escape