# Goose v1.49 本地 Canary 运行手册

> **2026-09-09 收口**：默认禁止真实 LLM 聚合 smoke（`check-goosed-v149-all` / phase2 / phase3 等）。见 [goose-v149-real-llm-gate.md](./goose-v149-real-llm-gate.md)。仅 `GOOSE_V149_ALLOW_REAL_LLM=1` + 明确批准后可跑。

> 范围：仅本机 loopback（`:18049` vs `:18006`），**禁止**连接 103/105 或修改生产 launchd。
> 决策表：[TKMIND_V1_49_MIGRATION.md](../TKMIND_V1_49_MIGRATION.md)

## 架构

```text
Portal (pnpm dev :8081)
    │
    ├─ TKMIND_GOOSE_CANARY=off     → TKMIND_API_TARGET=https://127.0.0.1:18006 (stable 1.41)
    ├─ TKMIND_GOOSE_CANARY=all     → TKMIND_API_TARGET=https://127.0.0.1:18049 (v1.49 候选)
    └─ TKMIND_GOOSE_CANARY=users   → 双 target；canary 用户路由到 v1.49（需 USER_IDS）
```

Memory 在 canary 期间保持 legacy owner（MySQL `h5_user_memory_items`），upstream goosed **不得**写入业务记忆。

## 前置条件

```bash
bash scripts/build-goosed-v149-local.sh
bash scripts/ensure-goose-v149-local-db.sh
# 默认已禁用；须明确批准：
GOOSE_V149_ALLOW_REAL_LLM=1 bash scripts/run-goosed-v149-local.sh    # 另开终端，监听 :18049
curl -sk https://127.0.0.1:18049/status   # → ok
```

## 一键开启 Canary（全量切到 v1.49）

```bash
bash scripts/switch-goose-v149-canary.sh on all
pnpm dev    # 重启 Portal 以加载 .env.local
node scripts/check-goosed-v149-canary-portal.mjs   # 隔离 :8083 验证（不干扰主 Portal）
```

> 已写入 `.env.local` canary 块。主 Portal `:8081` 须重启后才路由到 `:18049`。
> v1.49 已移植 `platform/web`（`web_search` / `fetch_url`）；验证：`node scripts/check-goosed-v149-web-smoke.mjs`。

脚本会在 `.env.local` 写入 `# GOOSE_V149_CANARY_BEGIN … END` 块，设置：

- `TKMIND_GOOSE_CANARY=all`
- `TKMIND_API_TARGET=https://127.0.0.1:18049`
- Memory 安全开关（legacy / vector off）
- `H5_PUBLIC_BASE_URL=http://127.0.0.1:8081`（避免 Vite `:5173` 未起时页面链接失效）

## 按用户 Canary（双 target）

```bash
export TKMIND_GOOSE_CANARY_USER_IDS="<your-user-uuid>"
bash scripts/switch-goose-v149-canary.sh on users
pnpm dev
```

Portal 会注册 `[18006, 18049]` 双 target；canary 用户的新 session 应 pin 到 v1.49（见 `scripts/goose-v149-canary.mjs` + `release-gate/canary-routing.mjs`）。

## 一键回滚（回落 stable）

```bash
bash scripts/switch-goose-v149-canary.sh rollback
pnpm dev
```

回滚仅移除 canary 块，不删 v1.49 进程或 PG 库；stable `:18006` 保持可用。

## 验证

```bash
# 以下默认 BLOCKED；须 GOOSE_V149_ALLOW_REAL_LLM=1 且有人值守，禁止 Agent 循环重跑：
# node scripts/run-goosed-v149-phase2.mjs
# node scripts/run-goosed-v149-phase3.mjs
# node scripts/check-goosed-v149-all.mjs

# 无 LLM 的对照 / 单测（推荐日常）：
node --test scripts/goose-v149-canary.test.mjs
node scripts/compare-goose-v149-message-sanitize.mjs
node scripts/compare-goose-v149-memory-manifest.mjs
node scripts/check-goosed-v149-memory-loop.mjs
node scripts/check-goosed-v149-portal-smoke.mjs   # 主 Portal 重启后
node scripts/check-goosed-v149-canary-portal.mjs    # 隔离 :8083
```

## Phase 0 基线采集

```bash
# Runtime 样本（status / sessions / 可选 SSE reply）
node scripts/capture-goose-v149-baseline.mjs

# Memory manifest（每用户 ID/hash/evidence/source session）
node scripts/export-goose-v149-memory-manifest.mjs --output docs/baselines/goose-v149-memory-latest.json
```

输出目录：`docs/baselines/`（git 可跟踪的本地基线 JSON）。

## 环境变量参考

见 [goose-v149-canary.env.example](./goose-v149-canary.env.example)。

| 变量 | 说明 |
|---|---|
| `TKMIND_GOOSE_CANARY` | `off` / `all` / `users` |
| `TKMIND_API_TARGET_STABLE` | 默认 `https://127.0.0.1:18006` |
| `TKMIND_API_TARGET_V149` | 默认 `https://127.0.0.1:18049` |
| `TKMIND_GOOSE_CANARY_USER_IDS` | 逗号分隔 user UUID（users 模式） |
| `GOOSE_V149_CANARY_ENV_FILE` | 默认 `.env.local` |

## 禁止项

- 不得把 `TKMIND_API_TARGET` 指向 103/105 公网或生产端口
- 不得在本阶段修改 103 launchd、105 nginx
- 不得启用 upstream Memory backend 写入 MySQL 业务表
- 生产发布仍须走 `main` + `check-release-ready.sh` + Gate report