2 Commits

Author	SHA1	Message	Date
JianFeeeee	6d38a164eb	chore(module): Go module 路径随托管地迁移 gitcode → github ... ## 背景 仓库早已迁移到 GitHub（`github.com/JianFeeeee/HomeAgent`，CI/CD 都在那边跑）， gitcode 保留为**国内只读镜像**（`ci.yml` 的 sync-gitcode-main 快进推送）。 但 go.mod 的 module 路径一直是 `gitcode.com/JianFeeeee/...` —— 既与权威源 不符，`meta.SourceURL`（AGPL §13 的源码提供入口）也指向镜像而非实际运行的代码。 ## 关键区分（这是本次改动安全的前提） 两个 module 是**不同**的，影响面差一个数量级： | module | 谁依赖 | 改它的后果 | |---|---|---| | `.../HomeAgent`（主仓） | **只有主仓自己** | 内部重构，零外部影响 | | `.../homeagent-sdk`（SDK 仓） | 主仓 49 文件 + 所有外部插件 | 需重编插件 | ★ 实测确认：**插件不 import 主仓 module**（`strings qq/plugin.bin | grep HomeAgent` = 0）， 只依赖 SDK 仓。而插件与内核的边界是 **RPC 方法名字符串** （`plugin.init` / `tool.invoke`…，见 proc/protocol.go），**与 Go module 名无关**。 ⇒ module 改名**不改变任何 wire 协议**，现网已装的插件照常运行。 SDK 的 GitHub 仓名是 `homeagentsdk`（无连字符），module 路径必须与之精确匹配， 否则 `go get` 会因路径不符失败，故取 `github.com/JianFeeeee/homeagentsdk`。 ## 改动 - `go.mod` / `go.sum`：两个 module 路径 + require/replace - 277 个 Go 文件 + Makefile + 打包脚本的 import 与 ldflags 路径 - SDK 仓 `meta.CoreModule`、`tools/hmapdev` 的 module 声明与工程模板 - 对外文档/链接的仓库地址（README、PLUGIN_DEV、OVERVIEW 等） ## 明确**保留** gitcode 的地方（镜像机制，不能动） - `GITCODE_TOKEN`、`GC_URL="…@gitcode.com"`（CI 同步 job） - `gitcode.com/api/v5/...`（release 附件上传） - git remote `gitcode`（镜像拉取/推送） - `docs/zh/ci-cd-runbook.md`（整篇讲镜像运维） ## 验证 - `go build ./...` / `go vet ./...` 绿 - `go test ./... -count=1` → 48 包 ok / 0 FAIL - hmapdev 工具链编译通过（`third_party/homeagent-sdk/tools/hmapdev`） - 全仓残留检查：module 形态的 `gitcode.com/JianFeeeee` = 0 - 镜像机制抽验：GC_URL / @gitcode / api/v5 / remote 均完好 ## 顺带修正 `hmapdev/templates.go` 的注释此前写「gitcode 的模块不在 proxy.golang.org 上」—— module 已迁 GitHub，该论断不再成立。改为如实说明**为何仍默认 replace 到本机 SDK**： 离线可构建、避免版本漂移、内网可用。理由与托管地无关，故 replace 保留。	2026-10-08 10:40:17 +08:00
JianFeeeee	7a712f843e	fix(knowledge): 知识库检索改为「稠密 + 词法」两路融合（真实 KB 自检索 MRR 0.271→0.376） ... 追「实例看起来没更新」时发现知识库检索本身也不可信，先把病因查清再动手： - **两段式召回不是瓶颈**：Store 的结果与全量暴力 cosine 完全一致； - **真因是向量没有区分度**：词向量取平均后各向异性明显，真实 KB（33 条）上自检索 top-1 只有 15%、前两名平均只差 0.013，排序基本是噪声； - 且全为停用词的查询会得到**空向量**（"最近更新"），直接搜不出任何东西。 先在真实数据上把候选方案量了一遍（用自检索 top-1 / MRR）再动手：IDF 维度加权零收益、 去均值反而更差，**都不做**；唯一有收益的是与词法路（TF-IDF）融合。 改动： - `Store` 增设词法路索引，`Search` 融合两路：各自按**查询内最大值**归一化后加权。 权重 0.5 由权重扫描定：1.0（旧行为）MRR 0.271 / 0.8→0.354 / 0.7→0.358 / **0.5→0.376** / 0.3→0.336 / 0.0→0.307；语义查询也从"全是 openharmony 噪声"变成命中正确条目 （「首启人格门禁」→changelog_v1.2.1、「插件怎么开发和部署」→plugin_dev_build）； - `vector.Store` 的候选中选阈值改为**可设**（默认 0.05 保持既有行为）：TF-IDF 余弦量级 只有 0.0~0.2，沿用 0.05 会把词法路有效候选**静默砍掉**——这一条正是 0.376→0.197 的 差距来源，且当时没有任何报错； - Add/Remove/scanAll/ReindexWithVectorizer 同步维护两路；分数相同时按名字定序（结果可重复）。 **顺带修一个真实毛病**：Add/Remove 原先用**无追踪的 goroutine** 写索引（因为 writeIndex→BuildTree 会 RLock，而调用方持写锁，同步调用会死锁）→ 失败只打日志， 且与调用方竞态（测试的临时目录清理就撞上了）。改为持锁就地 flush （buildTreeLocked / writeIndexLocked）。 判据（不依赖人工标注问答对）：新增 `internal/knowledge/rankdiag_test.go`，用**自检索 top-1 / MRR** 量区分度，`KB_DIAG=1` 跑、`KB_DIAG_ASSERT=1` 断言（MRR ≥ 0.34）。 另有不依赖真实数据的单测 6 条（空稠密向量靠词法路救回、稠密并列时词法路定序、 词法路阈值接线、Add/Remove 双路一致、并列时确定性、空库不 panic）。 **反向验证**（证明判据真能发现缺陷）：权重退回 1.0、词法路阈值改回 0.05、 把阈值写死回 0.05 —— 对应测试逐条变红。另：我第一版夹具余弦 0.365/0.273 远高于阈值， 注入缺陷也不报错（等于没验），故加了「夹具前提」断言并改成两层判据 （语义层由 vector 包测试证明、接线层由知识库测试钉住）。 顺带纳入上一轮漏提交的 `TestAddOverwriteReplacesVector`（同名覆盖必须摘掉旧向量， 生产改动当时已提交，测试一直未入库）。	2026-09-12 18:14:22 +08:00