From b2a2e4292bf966e77402c03480008d498c803eaa Mon Sep 17 00:00:00 2001
From: Windows <19353512109@163.com>
Date: Sat, 12 Sep 2026 14:35:49 +0800
Subject: [PATCH] =?UTF-8?q?docs(37):=20=E8=A1=A5=E3=80=8C=E6=8D=A2?=
 =?UTF-8?q?=E5=88=B0=E6=96=B0=E7=8E=AF=E5=A2=83=E5=BF=85=E9=A1=BB=E5=85=88?=
 =?UTF-8?q?=E5=81=9A=E3=80=8D=E7=9A=84=E5=89=8D=E7=BD=AE=E6=B8=85=E5=8D=95?=
 =?UTF-8?q?=EF=BC=88=E5=BB=BA=E9=9B=86=E5=90=88/Milvus/embedding=20?=
 =?UTF-8?q?=E7=AB=AF=E7=82=B9/=E8=BF=81=E7=A7=BB=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/37-记忆投影链路实现说明.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/37-记忆投影链路实现说明.md b/docs/37-记忆投影链路实现说明.md
index f42a340..f816f59 100644
--- a/docs/37-记忆投影链路实现说明.md
+++ b/docs/37-记忆投影链路实现说明.md
@@ -82,6 +82,21 @@
 建集合：`python tools/setup_milvus_profile_collection.py`
 ——**幂等**，集合已存在时只做结构比对报告、不覆盖不删重建（共享 Milvus 实例里还有别的项目的集合）。
 
+> ## ⚠️ 换到新环境（例如最终验收在架构师机器上跑）必须先做这一步
+>
+> **集合是环境数据，不随代码合并。** 本线的代码里没有、也不该有"自动建集合"的逻辑
+> （那会让"环境没准备好"被静默盖住）。所以在新机器上：
+
+| 前置 | 命令 | 不做的后果 |
+|---|---|---|
+| **建画像向量集合** | `python -X utf8 tools/setup_milvus_profile_collection.py` | `load_collection` 抛 `RecoverableAgentError("画像向量集合不可用")` ⇒ `memory_sync_outbox` 的 `milvus` 行**失败重试到死信**。**这是环境问题，不是代码缺陷** |
+| Milvus 可达 | `docker ps` 能看到 `milvus-standalone` 且 healthy | 同上；另注意 `MILVUS_LOCAL_URI` 若被设过会指向本地 Lite 文件、查的是另一个库 |
+| embedding 端点 | 发布配置里有 `task_type=embedding` 的端点 | `_profile_embed` 抛"没有可用的 embedding 端点"，事件同样重试到死信 |
+| 数据库迁移 | `alembic upgrade heads` | `memory_sync_outbox` / `memory_unit` 等表不存在 |
+
+> 建集合后可用 `python -X utf8 tools/setup_milvus_profile_collection.py` **再跑一次**确认输出为
+> `exists`（幂等，不会重复建）。
+
 ### `memory_sources` 契约（适配器的输入）
 
 ```json