memind/docs/local-dev.md

本地开发

这是本机本地开发文档，只处理当前工作区里的源码联调，不做任何生产同步。
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

H5 多个接口同时返回 500

如果 5173 页面里的 /auth/status、/auth/wechat/config、/api/analytics/context 同时返回 text/plain 500，先检查 Portal：

curl -i http://127.0.0.1:8081/auth/status

8081 无法连接表示 Vite 还在运行、但它代理的 Portal 已退出，并非这些路由同时故障。 前台 pnpm dev 会在任一受管子进程意外退出时结束整个开发栈；重新运行 pnpm dev 即可干净启动。LaunchAgent 模式则查看 ~/Library/Logs/memind-dev.log 并按下节命令重启。

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 架构

MindSpace：本地 vs 生产（必须区分）

pnpm dev / server.mjs 启动时会读取 MEMIND_RUNTIME_PROFILE（见 scripts/memind-runtime-profile.mjs）：

MEMIND_RUNTIME_PROFILE	用途	MindSpace 实现
local（默认）	本机日常开发	Portal 内置 MINDSPACE_SERVER_ADAPTER=local
split-service	本机验证 103 拆分架构	remote → http://127.0.0.1:8082 独立 MindSpace 服务
production	仅 103 服务器	不覆盖 .env，以服务器配置为准

本地 .env 推荐：

MEMIND_RUNTIME_PROFILE=local

本机要测 split-service 时：

MEMIND_RUNTIME_PROFILE=split-service
MINDSPACE_REMOTE_BASE_URL=http://127.0.0.1:8082
MINDSPACE_REMOTE_AUTH_TOKEN=local-dev-secret   # 必须与 MindSpace LaunchAgent 一致
launchctl kickstart -k "gui/$(id -u)/cn.tkmind.mindspace-service"
pnpm dev

如需验证 Goose 的逻辑 workspace MCP，再让 Portal 与 MindSpace Service 使用相同的本地签名 secret；该值至少 16 个字符，只放本机 .env， 不得提交：

MINDSPACE_MCP_BASE_URL=http://127.0.0.1:8082
MINDSPACE_MCP_TOKEN_SECRET=replace-with-a-local-secret
# 可选；默认 12 MiB，必须大于等于 1024
MINDSPACE_MCP_MAX_BODY_BYTES=12582912

Portal 用 secret 签发绑定 user/session/package/workspace/tool allowlist 的短期 token，MindSpace Service 用同一 secret 验证；Goose extension 只收到 scoped token，不会收到签名 secret。该 MCP 配置目前用于 split-service 联调。配置完整时 DOCX 目标写入和长图渲染也会经过 MindSpace Service；未配置时不会开放 publish_page，其它工具保留 本地兼容行为。

验证当前源码的本地 split-service 链路可运行：

npm run smoke:mindspace-split-service

该 smoke 会构建本地 .runtime/mindspace-service、启动临时独立 MindSpace RPC 服务，并通过 remote adapter 验证 health/contract、 workspace 写读、微信 HTML 交付与 fresh thumbnail；不会发布或上传 runtime artifact。它会读取本机配置的开发数据库并创建唯一的 split-service-smoke-* session/package 记录，退出时会清理对应 package/artifact，并把临时文件根删除。

remote adapter 会在 Portal 启动时校验 /mindspace/v1/contract 的 contractVersion、required capabilities 与关键 binding。如果本机 8082 仍是旧 MindSpace runtime，Portal 会 fail-fast，而不是等到 页面交付时才出现 Unknown binding。

排查 package / artifact / public URL 链路：

npm run audit:conversation-packages -- --limit 100
npm run trace:mindspace-artifact -- --public-url http://127.0.0.1:5173/MindSpace/<owner>/public/page.html

启动后 Portal 日志应出现：[Portal] Runtime profile: MEMIND_RUNTIME_PROFILE=local, MINDSPACE_SERVER_ADAPTER=local, ...

禁止： 把 103 生产 .env、RDS 连接串、MINDSPACE_REMOTE_AUTH_TOKEN 生产值复制进本机 Git 仓库。

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	9 个 goosed target（18006–18014），见 103 runtime topology
H5_PUBLIC_BASE_URL	http://127.0.0.1:5173	https://m.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。这相当于运行时止血；如果确认整版不要，再按代码回撤处理。