memind/docs/local-dev.md

# 本地开发

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

`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 |

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

### LaunchAgent 常驻（推荐本机联调）

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

```bash
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` 做前台调试；两者不要同时占用同一端口。重启服务：

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

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

```bash
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-architecture-20260706.md) |

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

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

```bash
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 |

启动后应看到类似：

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

回归：

```bash
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](./pending-fixes/h5-local-soak-20260706.md)

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

Plaza 本地开发说明见 [plaza-local.md](./plaza-local.md)。生产发布、同步与回滚不要在这里处理，统一看 [生产更新发布指南](./release-deploy.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](./103-runtime-topology.md) |
| `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`

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

```text
{H5_PUBLIC_BASE_URL}/webhooks/wechat-mp/messages
```

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

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

```bash
H5_WECHAT_MP_ENABLED=0
```

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