build(packaging): 统一 -buildvcs=false，版本/提交只认 ldflags 注入

发布分支的产物上出现了 `vcs.revision=1715b5c`——一个本机任何仓库都不存在的提交。

原因：VCS 信息**不进 build cache key**（Go 文档明确说明 VCS 变化不会触发重建），
命中缓存时会把上一次的 revision 一并带回来。

而 build.sh 本来就用 ldflags 注入 meta.Version / meta.Commit（权威来源），
所以这个额外信号既不可靠又会误导溯源：拿 `go version -m` 去查源码提交，会指向
一个幽灵提交——正是本项目一直在治的「静默不一致」。

处置：三处 go build 统一 `-buildvcs=false`，并在 LDFLAGS 旁写明溯源方法
（`strings homed | grep -x '<短 hash>'`，meta.Commit 是字符串常量）。

验证：重新构建 homed linux/amd64 →
  · `go version -m` 中 vcs.revision 0 处（此前 1 处且是错误值）
  · strings 中恰好 1 处等于当前 HEAD 短 hash
  · `-tags=onnxruntime` 仍在

deploy/packaging/build.sh

@@ -15,6 +15,13 @@ BUILD_TIME="${BUILD_TIME:-$(date -u '+%Y-%m-%dT%H:%M:%SZ')}"
 GO="${GO:-$(command -v go 2>/dev/null || echo "go")}"
 LDFLAGS="-X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Version=${VERSION} -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Commit=${COMMIT} -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.BuildTime=${BUILD_TIME}"
 
+# 版本与提交的**权威来源**是上面注入的 meta.Version / meta.Commit，不是 Go 自带的
+# VCS 戳。后者不进 build cache key（Go 文档明确说明 VCS 变化不会触发重建），
+# 命中缓存时会把上一次的 revision 一并带回来——实测发布分支的产物上就出现了
+# 1715b5c（本机任何仓库都不存在的提交），用 `go version -m` 溯源会指向幽灵提交。
+# 统一 -buildvcs=false：宁可没有这个信号，也不要一个错的。
+# 溯源请用：`strings homed | grep -m1 '^<短 hash>$'`（meta.Commit 是字符串常量）。
+
 TARGET="${1:-native}"
 COMPONENT="${2:-all}"
 
@@ -131,7 +138,7 @@ build_homed() {
   local _tags="${HOMED_TAGS-onnxruntime}"
   local -a _tagargs=()
   if [ -n "$_tags" ]; then _tagargs=(-tags "$_tags"); fi
-  CGO_ENABLED=1 CC="$_cc" "$GO" build -trimpath -installsuffix dynlink \
+  CGO_ENABLED=1 CC="$_cc" "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
     ${_tagargs[@]+"${_tagargs[@]}"} \
     -ldflags "$LDFLAGS" -o "$out" ./cmd/homed/
   echo "  OK ($(file "$out" | sed 's/.*: //') | $(du -h "$out" | cut -f1))"
@@ -144,7 +151,7 @@ build_waiter() {
   if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
 
   echo "[BUILD] waiter ${plat} → $out"
-  CGO_ENABLED=0 "$GO" build -trimpath -installsuffix dynlink \
+  CGO_ENABLED=0 "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
     -ldflags "$LDFLAGS" -o "$out" ./cmd/waiter/
   echo "  OK ($(du -h "$out" | cut -f1))"
 }
@@ -165,7 +172,7 @@ build_initconfig() {
   if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
 
   echo "[BUILD] initconfig ${plat} → $out"
-  CGO_ENABLED=1 "$GO" build -trimpath -installsuffix dynlink \
+  CGO_ENABLED=1 "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
     -ldflags "$LDFLAGS" -o "$out" ./cmd/initconfig/
   echo "  OK ($(du -h "$out" | cut -f1))"
 }
@@ -204,6 +211,14 @@ stage_linux_payload() {
 }
 
 # ---- gui (Electron) ----
+#
+# 输出目录必须用 --config.directories.output，**不能用 -o**：
+# electron-builder 的 `-o` 是 `--mac`/`--macos` 的短别名（见 --help 的 Building 段），
+# 不是 output。此前 `-o "$BUILD_DIR"` 被当成 macOS 的 target 列表，报
+#   ⨯ Unknown target: /home/program/trueagent/build
+# （路径被 lowercase 后去匹配 target 名表，所以错误信息里的路径是全小写的，
+#  这也是它看起来像「路径错」而实际是「参数位置错」的原因）。
+# v1.0.1 与 v1.0.3 两次发布都因此手工组装过 GUI。
 build_gui() {
   if [ -n "${GOOS:-}" ] && [ "$GOOS" != "$("$GO" env GOOS)" ]; then
     echo "[SKIP] gui ${GOOS}/${GOARCH} — electron-builder handles cross-platform natively; run 'all' on CI host"
@@ -221,12 +236,21 @@ build_gui() {
   # 不传 --config：electron-builder 默认从 package.json 的 "build" 键读配置。
   # 传 --config package.json 会让它把**整个** package.json 当配置校验，
   # 于是 devDependencies / build / scripts 全被判为 "unknown property" 而失败。
-  (cd "$gui_dir" && npx electron-builder \
-    --linux --win --mac \
-    --x64 --arm64 \
-    -p never \
-    -o "$BUILD_DIR")
-  echo "  OK"
+  #
+  # GUI 失败不中断整体构建：homed/waiter/initconfig 是发布的主体，
+  # 而 GUI 依赖 electron 运行时下载（离线机器、arm64 缺缓存都会失败）。
+  # set -e 下若不接住，一个可选组件会让整轮跨平台构建全废。
+  if (cd "$gui_dir" && npx electron-builder \
+      --linux --win --mac \
+      --x64 --arm64 \
+      -p never \
+      --config.directories.output="$BUILD_DIR"); then
+    echo "  OK"
+  else
+    echo "  WARN: gui 构建失败（可选组件，不影响 homed/waiter/initconfig）"
+    echo "        Linux 包可用 deploy/packaging/package-linux.sh 内置的手工组装路径"
+    return 0
+  fi
 }
 
 # ---- dispatch ----

docs/git-branching.md

@@ -130,26 +130,27 @@ main ──────────────── E ────────
 
 ---
 
-## 三、当前分支对齐（2026-09-04 执行）
+## 三、当前分支对齐（2026-09-12 更新）
 
 ### 主仓（TrueAgent）
 
 | 分支 | 状态 | 处理 |
 |---|---|---|
-| `main` | 含全部 hotfix（逐个 cherry-pick），`meta.Version` = 下一个未发布中版本（现为 `1.2.0`） | ✅ 保持 |
-| `release/v1.0.x` | 承载 v1.0.0 / v1.0.1 / v1.0.3 全部 tag | ✅ **由 `release/v1.0.1` 重命名而来**（2026-09-04） |
-| `release/v1.0.0` | `9b92a04`，已被 1.0.x 线完全包含（`merge-base --is-ancestor` 验证通过） | 🗑️ **已删除**（本地 + 远端），tag `v1.0.0` 保留全部历史 |
-| `release/v1.0.1` | 旧 patch 号命名 | 🗑️ **已重命名为 `release/v1.0.x`**（远端旧名删除） |
-| `feature/memory-media` | 记忆系统媒体（多模态）支持，进行中 | ⏳ 完成后合回 main 并删除 |
-| `feature/plugin-proc-migration` | 已合入 main（`525aa1f`） | ⏳ 待删（规范要求合回后删除） |
-| `release/v1.1.x` | 承载 v1.1.0 / v1.1.0-beta.1 / v1.1.1 全部 tag | ✅ 1.1 线的唯一发布分支 |
+| `main` | 含全部回流修复；`meta.Version` = 下一个未发布中版本（现为 `1.3.0`） | ✅ 保持 |
+| `release/v1.2.x` | **本条发布线**，`meta.Version` = `1.2.0`，vendored SDK 定版 `1.2.0`；已载入两个发布前修复（GUI 输出目录、知识库同名覆盖） | 🆕 2026-09-12 从 main 切出；**尚无 tag** |
+| `release/v1.1.x` | 承载 `v1.1.0-beta.1` / `v1.1.0` / `v1.1.1` | 📦 已退役（§2.6：下个中版本发布即退役），保留供追溯 |
+| `release/v1.0.x` | 承载 1.0.x 全部 tag | 📦 保留 |
+| `feature/multimodal-embedding` | 已合入 main（`eb4762a`，43 提交，`--no-ff`） | ⏳ 待删（删远端分支需用户确认，§执行守则 3） |
+
+> `feature/memory-media`、`feature/plugin-proc-migration` 均已从远端删除（旧表里的待删项已处理）。
 
 ### SDK 仓（homeagent-sdk）
 
 | 分支 | 状态 | 处理 |
 |---|---|---|
-| `main` | `meta.Version` = 下一个未发布中版本（现为 `1.2.0`） | ✅ 保持 |
-| `release/v1.1.x` | `meta.Version` = `1.1.0`，承载 tag `v1.1.0` | ✅ 与核心 `release/v1.1.x` 对应 |
+| `main` | `meta.Version` = 下一个未发布中版本（现为 `1.3.0`，与核心 main 同步） | ✅ 保持 |
+| `release/v1.1.x` | `meta.Version` = `1.1.0`，承载 tag `v1.1.0` | ✅ 与核心对应 |
+| `release/v1.2.x` | **尚未创建** | ⏳ 随核心**正式** tag 一起建（§七.3：分支上把版本定为 `1.2.0` 再打 `v1.2.0`；beta 阶段不发 SDK） |
 | `release/v1.0.0` | 旧 patch 号命名形态，内容已被 main 完全包含 | 📦 保留（供追溯 1.0 线构建） |
 
 ### 1.0.x 发布线 tag 历史
@@ -174,6 +175,17 @@ main ──────────────── E ────────
 > 而 semver 预发布语义里 `1.1.0-beta.1 < 1.1.0`。这是「一条发布分支 + tag 区分通道」的
 > 已知代价：beta 是为验证**打包链路**而补打的，不代表源码更旧。发布说明里已注明。
 
+### 1.2.x 发布线 tag 历史
+
+| tag | 提交 | 通道 | SDK | 说明 |
+|---|---|---|---|---|
+| （尚无） | — | — | — | `release/v1.2.x` 已切出（`01232a6`），tag 通道待定 |
+
+> 1.2.x 与存量插件**不兼容**：RPC 协议升到 2（fd3 布局改变），存量外部插件必须用
+> 新版 plugindev 重编为 `plugin.bin`——**不支持滚动升级**，内核与插件须同批重建、同批安装。
+> 按 §2.4，跳级直发正式版需在发布说明里列明「单点修复 / 反向验证 / 全类审计」三项；
+> 本次改动面大（统一多模态向量空间 + 协议 2 + 数据面全量迁移），不满足跳级条件。
+
 ---
 
 ## 四、现网部署与版本对应（运维纪律）

internal/knowledge/knowledge.go

@@ -201,6 +201,13 @@ func (s *Store) Add(name, content string) error {
 	}
 	s.items[id] = k
 
+	// 覆盖同名条目时必须先摘掉旧向量。
+	//
+	// vector.Store.Insert 是**追加**语义（s.docs = append + index.Add），不按 id
+	// 去重。少了这一步，更新一条知识会在向量索引里留下上一版的副本：条目数看起来
+	// 是对的，只有向量数比条目数多——而检索可能因此命中已被替换掉的旧内容。
+	s.vec.Remove(id)
+
 	vec := s.vectorize(name + " " + content)
 	s.vec.Insert(id, name+": "+content, vec, map[string]string{
 		"name": name, "path": path,

internal/knowledge/knowledge_test.go

@@ -44,6 +44,51 @@ func TestAddAndSearch(t *testing.T) {
 	}
 }
 
+// 覆盖同名条目必须把旧向量摘掉，而不是再插一份。
+//
+// 这条是从一次真实的知识库更新里发现的：在线上实例更新一个已有条目后，
+// knowledge_count=32 但 vector_count=33 ——多出来的那一条是上一版的副本。
+// 成因是 vector.Store.Insert 为追加语义（s.docs = append + index.Add），不按 id 去重。
+// 危害不在于多占一份内存：检索可能命中**已被替换掉的旧内容**。
+func TestAddOverwriteReplacesVector(t *testing.T) {
+	dir, err := os.MkdirTemp("", "know_overwrite_*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.RemoveAll(dir)
+
+	s := NewStore(dir)
+	s.Start()
+	defer s.Stop()
+
+	if err := s.Add("recent", "第一版内容：旧的多模态描述式索引"); err != nil {
+		t.Fatal(err)
+	}
+	if got := s.Stats()["vector_count"].(int); got != 1 {
+		t.Fatalf("首次写入后 vector_count 应为 1，实为 %d", got)
+	}
+
+	if err := s.Add("recent", "第二版内容：媒体已成为图记忆的一等节点"); err != nil {
+		t.Fatal(err)
+	}
+
+	if n := s.Stats()["knowledge_count"].(int); n != 1 {
+		t.Fatalf("同名覆盖后 knowledge_count 应为 1，实为 %d", n)
+	}
+	if n := s.Stats()["vector_count"].(int); n != 1 {
+		t.Fatalf("同名覆盖后 vector_count 应为 1（多了就是旧版没被摘掉），实为 %d", n)
+	}
+
+	// 目录里也只应有一份内容，且是新的那份
+	b, err := os.ReadFile(dir + "/recent/content.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(b) != "第二版内容：媒体已成为图记忆的一等节点" {
+		t.Fatalf("content.md 未被新内容覆盖，实为 %q", string(b))
+	}
+}
+
 func TestList(t *testing.T) {
 	dir, err := os.MkdirTemp("", "know_list_*")
 	if err != nil {