feat(context): add offline shadow profile and local dev gate

Provide context-runtime-profile simulation for gateway shadow events, run-context-runtime-offline.mjs for zero-LLM verification, and a local dev guide for user-led shadow self-tests later. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 22:18:47 +08:00
parent c6209370d8
commit 478c33376c
6 changed files with 405 additions and 9 deletions
@@ -0,0 +1,92 @@
+# Context Runtime 本地离线开发
+
+> 不调用 LLM、不跑 phase3 live smoke。用户自测见文末清单。
+
+## 一键离线验证
+
+```bash
+node scripts/run-context-runtime-offline.mjs
+node scripts/run-goosed-v149-phase3-offline.mjs   # 含 v1.49 单测 + manifest drift
+```
+
+通过时应分别输出 **`CONTEXT_RUNTIME_OFFLINE_OK`** 与 **`GOOSE_V149_PHASE3_OFFLINE_OK`**。
+
+## 推荐 shadow 配置（仅观测，不改行为）
+
+写入 `.env.local`（或临时 export）：
+
+```bash
+MEMIND_HEADROOM_MODE=shadow
+MEMIND_CONTEXT_BUDGET_MODE=shadow
+MEMIND_RECALL_FUSION_MODE=shadow
+MEMIND_MCP_COMPACT_MODE=shadow
+MEMIND_ZVEC_WORKSPACE_MODE=shadow
+HEADROOM_OUTPUT_SHAPER=0
+```
+
+Bundle 常量见 `context-runtime-profile.mjs` → `CONTEXT_RUNTIME_SHADOW_ENV`。
+
+## 离线事件形状预览
+
+不启动 Portal 也可查看 gateway 将 emit 的 shadow 事件：
+
+```bash
+node -e "
+import { simulateContextRuntimeShadowEvents } from './context-runtime-profile.mjs';
+console.log(JSON.stringify(simulateContextRuntimeShadowEvents(), null, 2));
+"
+```
+
+期望事件类型：
+
+| event_type | 含义 |
+|---|---|
+| `headroom_context_observed` | headroom 路由/eligible 观测 |
+| `context_budget_resolved` | 注入预算 dedupe/drop 计划 |
+| `recall_fusion_resolved` | 多路 recall 融合统计 |
+
+## 组件探针（可选）
+
+```bash
+# headroom proxy 已起且 MEMIND_HEADROOM_MODE!=off
+node scripts/check-headroom-proxy-local.mjs
+
+# .zvec-grep 已 index
+node scripts/check-zvec-workspace-local.mjs
+
+# MCP compactor shadow/active 逻辑
+node scripts/check-mcp-compactor-local.mjs
+```
+
+## 用户自测清单（有 LLM 配额时）
+
+1. 确认 **未设置** `GOOSE_V149_ALLOW_REAL_LLM=1` 除非你明确要跑 live smoke
+2. 应用 shadow env，**重启 Portal**（`pnpm dev`）
+3. 发起 **一轮**普通 agent 对话（非 page-e2e）
+4. 查 DB 事件：
+
+```sql
+SELECT event_type, data_json, created_at
+FROM h5_agent_run_events
+WHERE run_id = '<run_id>'
+  AND event_type IN (
+    'headroom_context_observed',
+    'context_budget_resolved',
+    'recall_fusion_resolved'
+  )
+ORDER BY created_at;
+```
+
+5. 确认 `mode=shadow` 且 **聊天行为与 off 时一致**
+6. 若要 active 晋升：逐项改 `shadow` → `active`，每次只改一个开关
+
+## 禁止项
+
+- Agent **不得**自动设置 `GOOSE_V149_ALLOW_REAL_LLM=1` 或循环跑 phase2/phase3
+- **禁止** `headroom wrap` / `headroom learn` / `HEADROOM_OUTPUT_SHAPER=1`
+- 页面生成 / Page Data 轮次首期 **排除** headroom active
+
+## 相关文档
+
+- [context-runtime-harness-fusion-plan.md](./context-runtime-harness-fusion-plan.md)
+- [goose-v149-real-llm-gate.md](./goose-v149-real-llm-gate.md)