From 8cd3793336d82dad1fe2b2389bcd42589b4071e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=94=AF?= Date: Tue, 3 Nov 2026 03:07:34 +0800 Subject: [PATCH] =?UTF-8?q?feat(recall):=20B1=20=E7=AC=AC=E4=BA=8C?= =?UTF-8?q?=E8=B7=AF=20skill=20=E5=88=86=E8=8A=82=E6=A3=80=E7=B4=A2=20skil?= =?UTF-8?q?l=5Frefs=EF=BC=88t=5Fe3f5cb79=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - routes/skillrefs.go:~/.hermes/skills/**/*.md 分节索引(H2~H4), BM25(k1=1.5,b=0.75) + 停用字过滤 + 微型领域同义/中英扩展表 + 行级共现(最佳行主导)+ 文件名主题先验 + SKILL.md 权威先验; 纯 stdlib 零新依赖;索引 37k 节 ~300ms,10min 懒重建 - /api/v1/recall 响应新增顶层 skill_refs:[{path,snippet,matched}](n=5), memories(results) 结构一字不动,两路不混排;键恒存在(含 system_template 早退路径) - 开关 ZHIYI_RECALL_SKILLREFS 默认关;ZHIYI_SKILLS_DIR 可覆盖索引源 - 测试:开关语义/停用词/fixture 形状 + 真实语料 AC-2.3 探针①② (缓存层→含 RedisCache 的 misc-topics.md;Go Rust 启动顺序→含 「先 Go」的 zhiyi-deploy-and-metrics.md) - 调试教训:自造线性权重在真实语料被疑问句共现带偏 → 换 BM25; 线性行累加让目录页刷分 → 最佳行主导 --- go/internal/api/routes/core.go | 6 + go/internal/api/routes/skillrefs.go | 594 +++++++++++++++++++++++ go/internal/api/routes/skillrefs_test.go | 168 +++++++ go/internal/distill/conflict_gate.go | 13 +- 4 files changed, 775 insertions(+), 6 deletions(-) create mode 100644 go/internal/api/routes/skillrefs.go create mode 100644 go/internal/api/routes/skillrefs_test.go diff --git a/go/internal/api/routes/core.go b/go/internal/api/routes/core.go index 0dc80b3..9756e8c 100644 --- a/go/internal/api/routes/core.go +++ b/go/internal/api/routes/core.go @@ -539,6 +539,7 @@ func (a *API) Recall(w http.ResponseWriter, r *http.Request) { "candidates_scanned": 0, "mode": req.Mode, "skipped": "system_template", + "skill_refs": []SkillSectionRef{}, // 契约:键恒存在(AC-2.1) }) return } @@ -968,6 +969,11 @@ func (a *API) Recall(w http.ResponseWriter, r *http.Request) { // 2026-10-26 (t_9025b0eb):扩展结果单独成字段,避免撑爆 results。 // 键恒存在(可为空数组),便于探针/统计区分「无扩展」与「字段缺失」。 "graph_expanded": graphExpanded, + // AC-2.1(t_e3f5cb79 · B1):第二路 skill 分节检索,**分栏不混排** —— + // 键恒存在;开关 ZHIYI_RECALL_SKILLREFS 关 / 任何失败 ⇒ []。 + // 「怎么做/为什么」类答案稳定落在 skill 文档而从不进 memories 表 + // (2026-10-31 方案验证节),这里补第二条通道,results 结构一字不动。 + "skill_refs": skillRefsForQuery(req.Query, 5), // t_1c12e000:AC3 —— 缓存命中/回源扫表必须可区分。 "cache_hit": cacheHit, // 2026-10-26(P0-1/P0-3 契约): diff --git a/go/internal/api/routes/skillrefs.go b/go/internal/api/routes/skillrefs.go new file mode 100644 index 0000000..11ad883 --- /dev/null +++ b/go/internal/api/routes/skillrefs.go @@ -0,0 +1,594 @@ +// 织忆 MemoryWeave — recall 第二路:skill 分节检索(t_e3f5cb79 · 2026-10-31 方案 B1) +// +// 根因(方案「验证结果(2026-11-02)」节):知识与记忆是两套互不相通的库 —— +// 「怎么做/为什么」类答案稳定落在 skill 文档(部署顺序/缓存分层/排障步骤), +// 从来不进 memories 表;recall 只查前者 ⇒ 答不了。 +// +// 本文件 = recall 的第二路(分栏返回,不混排): +// +// · 索引源 ~/.hermes/skills/**/*.md(env ZHIYI_SKILLS_DIR 可覆盖;3545 档 / 27MB) +// · 分节(H2~H4 标题切段)+ 关键词匹配(ASCII token 整词 + CJK bigram), +// 纯 stdlib,零新依赖、零外部服务(不依赖 embed/LLM —— 10-31 向量前案 +// 依赖 .vec.npy + embed 服务,shape 也不满足本卡 AC,见卡评论裁定 4) +// · 输出顶层 `skill_refs: [{path, snippet, matched}]`;`results`(记忆路) +// 结构一字不动,两路内容互不混入(AC-2.4,结构上保证) +// · 开关 ZHIYI_RECALL_SKILLREFS(默认关;每次读 env,测试可翻转) +// · 任何失败(目录缺失/IO 错误/查询为空)⇒ 返回空数组,主召回零影响 +// +// 精度取向(对齐方案验证节教训「先拿真实问题量一下」): +// +// · ASCII 标识符权重高(RedisCache/ZHIYI_* 这类精确 token 是主要判别信号) +// · CJK bigram 按段落长度做 sqrt 归一,防长段落靠撞 bigram 霸榜 +// · 每个文件只出最高分一节(top-3 文件),避免同文件刷屏 +package routes + +import ( + "log" + "math" + "os" + "path/filepath" + "regexp" + "sort" + "strings" + "sync" + "time" + "unicode" +) + +// SkillSectionRef 一条 skill 片段引用(AC-2.1 形状:path/snippet/matched)。 +type SkillSectionRef struct { + Path string `json:"path"` + Snippet string `json:"snippet"` + Matched []string `json:"matched"` + Score float64 `json:"-"` // 排序分(仅回归/调试可见;AC-2.1 线格式仍为 path/snippet/matched) +} + +// skillSection 索引单元:一个 Markdown 分节。 +type skillSection struct { + path string // 绝对路径 + title string // 分节标题(无标题=文件名) + lower string // 正文小写(ASCII 匹配用) + runeLen int // 正文字符数(长度归一用) + titleLow string // 标题小写(标题命中加权) + isSkillMd bool // SKILL.md 主文档(权威综述先验) +} + +type skillRefIndex struct { + sections []*skillSection + builtAt time.Time + avgRuneLen float64 +} + +var ( + skillIdxMu sync.RWMutex + skillIdxCache *skillRefIndex +) + +const ( + skillRefRebuildEvery = 10 * time.Minute + skillRefMaxFileBytes = 512 * 1024 + skillRefMaxSection = 8000 // rune + skillRefSnippetRunes = 200 +) + +// skillRefsEnabled 第二路开关(默认关 = 现网零变化;unit drop-in 置 1 启用)。 +func skillRefsEnabled() bool { + switch strings.ToLower(strings.TrimSpace(os.Getenv("ZHIYI_RECALL_SKILLREFS"))) { + case "1", "true", "on": + return true + } + return false +} + +func skillRefsDir() string { + if v := strings.TrimSpace(os.Getenv("ZHIYI_SKILLS_DIR")); v != "" { + return v + } + home, err := os.UserHomeDir() + if err != nil { + return "" + } + return filepath.Join(home, ".hermes", "skills") +} + +// headingRe H2~H4 标题行 = 分节边界。 +var headingRe = regexp.MustCompile(`^#{2,4}\s+(.*)$`) + +// buildSkillRefIndex 扫目录建分节索引(失败返回 nil,调用方降级空数组)。 +func buildSkillRefIndex(dir string) *skillRefIndex { + if dir == "" { + return nil + } + idx := &skillRefIndex{builtAt: time.Now()} + var walkErr int + _ = filepath.WalkDir(dir, func(p string, d os.DirEntry, err error) error { + if err != nil { + walkErr++ + return nil // 单点 IO 失败不中断整体 + } + if d.IsDir() { + // 隐藏目录(.archive/.vec 缓存等)不进索引 + if p != dir && strings.HasPrefix(d.Name(), ".") { + return filepath.SkipDir + } + return nil + } + if !strings.HasSuffix(d.Name(), ".md") { + return nil + } + if fi, e := d.Info(); e != nil || fi.Size() > skillRefMaxFileBytes { + return nil + } + raw, e := os.ReadFile(p) + if e != nil { + walkErr++ + return nil + } + addSkillFile(idx, p, string(raw)) + return nil + }) + log.Printf("[skillrefs] 索引就绪:sections=%d walk_errors=%d dir=%s 用时=%s", + len(idx.sections), walkErr, dir, time.Since(idx.builtAt).Round(time.Millisecond)) + if len(idx.sections) == 0 { + return nil + } + var sum int + for _, s := range idx.sections { + sum += s.runeLen + } + idx.avgRuneLen = float64(sum) / float64(len(idx.sections)) + return idx +} + +// addSkillFile 按 H2~H4 切节;YAML frontmatter 跳过。 +func addSkillFile(idx *skillRefIndex, path, content string) { + lines := strings.Split(content, "\n") + i := 0 + // frontmatter + if len(lines) > 0 && strings.TrimSpace(lines[0]) == "---" { + for j := 1; j < len(lines); j++ { + if strings.TrimSpace(lines[j]) == "---" { + i = j + 1 + break + } + } + } + title := "(front)" + var body strings.Builder + flush := func() { + txt := strings.TrimSpace(body.String()) + if txt == "" && title == "(front)" { + return + } + if txt == "" { + return // 只有标题没有正文的分节不进索引 + } + rs := []rune(txt) + if len(rs) > skillRefMaxSection { + txt = string(rs[:skillRefMaxSection]) + } + idx.sections = append(idx.sections, &skillSection{ + path: path, + title: title, + lower: strings.ToLower(txt), + runeLen: len(rs), + titleLow: strings.ToLower(title), + isSkillMd: filepath.Base(path) == "SKILL.md", + }) + } + for ; i < len(lines); i++ { + if m := headingRe.FindStringSubmatch(lines[i]); m != nil { + flush() + body.Reset() + title = strings.TrimSpace(m[1]) + continue + } + body.WriteString(lines[i]) + body.WriteByte('\n') + } + flush() +} + +// getSkillRefIndex 取索引(懒建 + 定期重建;重建阻塞在锁内,一次尖刺可接受)。 +func getSkillRefIndex() *skillRefIndex { + skillIdxMu.RLock() + idx := skillIdxCache + skillIdxMu.RUnlock() + if idx != nil && time.Since(idx.builtAt) < skillRefRebuildEvery { + return idx + } + dir := skillRefsDir() + newIdx := buildSkillRefIndex(dir) + if newIdx == nil { + return idx // 建索引失败:保留旧索引(可能为 nil = 空) + } + skillIdxMu.Lock() + skillIdxCache = newIdx + skillIdxMu.Unlock() + return newIdx +} + +// skillStopCJK 疑问/系词/量词类停用字:含这些字的 bigram 不参与打分 —— +// 真实语料实测「有哪些」类疑问句在全库高频共现,不排除则疑问句段落霸榜 +// (2026-11-03 调试:q=织忆有哪些缓存层 时 [有哪 哪些] 组合霸榜 8/10)。 +var skillStopCJK = map[rune]bool{ + '有': true, '哪': true, '些': true, '什': true, '么': true, '怎': true, '样': true, + '如': true, '何': true, '是': true, '的': true, '了': true, '吗': true, '呢': true, + '和': true, '与': true, '或': true, '在': true, '对': true, '从': true, '里': true, + '多': true, '少': true, '谁': true, '几': true, '该': true, '吧': true, '呀': true, +} + +func isHan(r rune) bool { return unicode.Is(unicode.Han, r) } + +// skillGlossary 微型近义/中英扩展表(查询侧,只扩 1 跳): +// 纯词面匹配桥不过的真实案例(2026-11-03 调试)——「缓存层」文档写 `RedisCache`、 +// 「启动顺序」文档写「部署时序」。表刻意小:只收运维域高频等价对。 +// 扩展词用 Contains 匹配(cache 允许出现在 RedisCache 内),权重 ×0.8。 +var skillGlossary = map[string][]string{ + "缓存": {"cache"}, "启动": {"重启", "部署"}, "重启": {"启动", "部署"}, + "部署": {"启动", "重启"}, "顺序": {"时序", "次序"}, "时序": {"顺序"}, + "端口": {"port"}, "服务": {"service"}, +} + +func skillExpand(cjk []string) []string { + out := []string{} + for _, t := range cjk { + for _, syn := range skillGlossary[t] { + out = append(out, syn) + } + } + return dedupeTerms(out) +} + +// filterOut 去掉已存在于 have 的词。 +func filterOut(terms, have []string) []string { + seen := make(map[string]bool, len(have)) + for _, h := range have { + seen[h] = true + } + out := terms[:0:0] + for _, t := range terms { + if !seen[t] { + out = append(out, t) + } + } + return out +} + +// skillQueryTerms 查询分词:ASCII token(≥2 字符,小写)+ CJK bigram(停用字过滤)。 +func skillQueryTerms(q string) (ascii, cjk []string) { + var cur strings.Builder + flushASCII := func() { + if cur.Len() >= 2 { + ascii = append(ascii, cur.String()) + } + cur.Reset() + } + rs := []rune(q) + // CJK bigram(过滤停用字 bigram) + var run []rune + flushRun := func() { + for k := 0; k+1 < len(run); k++ { + if skillStopCJK[run[k]] || skillStopCJK[run[k+1]] { + continue + } + cjk = append(cjk, string(run[k:k+2])) + } + run = run[:0] + } + for _, r := range rs { + switch { + case unicode.Is(unicode.Han, r): + flushASCII() + run = append(run, r) + case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_', r == '-': + flushRun() + cur.WriteRune(unicode.ToLower(r)) + default: + flushASCII() + flushRun() + } + } + flushASCII() + flushRun() + return dedupeTerms(ascii), dedupeTerms(cjk) +} + +func dedupeTerms(in []string) []string { + seen := make(map[string]bool, len(in)) + out := in[:0:0] + for _, s := range in { + if !seen[s] { + seen[s] = true + out = append(out, s) + } + } + return out +} + +// wordCount 词边界计数:token 前后不能贴字母/数字(防 `go` 命中 golang/google、 +// `rust` 命中 x-rustc 之类子串噪声 —— 真实语料实测短 token 子串匹配 df 虚高)。 +var wordBoundaryOK = func(b byte) bool { + return !(b >= 'a' && b <= 'z' || b >= 'A' && b <= 'Z' || b >= '0' && b <= '9' || b == '_') +} + +func wordCount(lower, token string) int { + n, from := 0, 0 + for { + i := strings.Index(lower[from:], token) + if i < 0 { + return n + } + i += from + j := i + len(token) + beforeOK := i == 0 || wordBoundaryOK(lower[i-1]) + afterOK := j == len(lower) || wordBoundaryOK(lower[j]) + if beforeOK && afterOK { + n++ + } + from = i + 1 + } +} + +// skillRefsForQuery 第二路检索入口:query → top-n skill 分节引用。 +// 关闭/无索引/空查询 ⇒ 空切片(非 nil,JSON 序列化为 [])。 +// 打分 = BM25(k1=1.5, b=0.75;tf 饱和 + 平均长度归一,标准 IR 做法): +// 2026-11-03 调试教训 —— 自造线性权重在 37k 分节真实语料上被「疑问句共现」 +// 与「长度/稀有 bigram」反复带偏,换教科书公式一次到位。 +func skillRefsForQuery(query string, n int) []SkillSectionRef { + out := []SkillSectionRef{} + if !skillRefsEnabled() { + return out + } + idx := getSkillRefIndex() + if idx == nil { + return out + } + ascii, cjk := skillQueryTerms(query) + if len(ascii) == 0 && len(cjk) == 0 { + return out + } + if n <= 0 || n > 30 { + n = 3 + } + + type hit struct { + sec *skillSection + score float64 + matched []string + } + // 单字兜底通道词条:查询里的非停用汉字(去重) + queryUnigrams := []string{} + seenU := map[rune]bool{} + for _, r := range query { + if isHan(r) && !skillStopCJK[r] && !seenU[r] { + seenU[r] = true + queryUnigrams = append(queryUnigrams, string(r)) + } + } + + // 扩展通道词(近义/中英,Contains 匹配) + expanded := skillExpand(cjk) + expanded = filterOut(expanded, append(append([]string{}, cjk...), ascii...)) + + // df 预扫(一遍 Contains) + df := make(map[string]int, len(ascii)+len(cjk)) + unigramDF := make(map[string]int, len(queryUnigrams)) + expandedDF := make(map[string]int, len(expanded)) + for _, sec := range idx.sections { + for _, t := range ascii { + if wordCount(sec.lower, t) > 0 { + df[t]++ + } + } + for _, t := range cjk { + if strings.Contains(sec.lower, t) { + df[t]++ + } + } + for _, r := range queryUnigrams { + if strings.Contains(sec.lower, r) { + unigramDF[r]++ + } + } + for _, t := range expanded { + if strings.Contains(sec.lower, t) { + expandedDF[t]++ + } + } + } + total := float64(len(idx.sections)) + bmIDF := func(d int) float64 { + return math.Log(1 + (total-float64(d)+0.5)/(float64(d)+0.5)) + } + avgLen := idx.avgRuneLen + if avgLen <= 0 { + avgLen = 600 + } + const k1, b = 1.5, 0.75 + bm := func(tf int, idf, secLen float64) float64 { + if tf == 0 { + return 0 + } + return idf * float64(tf) * (k1 + 1) / (float64(tf) + k1*(1-b+b*secLen/avgLen)) + } + + hits := make([]hit, 0, 64) + for _, sec := range idx.sections { + score := 0.0 + var matched []string + secLen := float64(sec.runeLen) + for _, t := range ascii { + tf := wordCount(sec.lower, t) + if tf > 0 { + score += 3.0 * bm(tf, bmIDF(df[t]), secLen) // ASCII 标识符是强信号 + matched = append(matched, t) + if strings.Contains(sec.titleLow, t) { + score += 2.0 // 标题命中加权 + } + } + } + for _, t := range cjk { + tf := strings.Count(sec.lower, t) + if tf > 0 { + score += bm(tf, bmIDF(df[t]), secLen) + matched = append(matched, t) + if strings.Contains(sec.titleLow, t) { + score += 1.5 + } + } + } + for _, t := range expanded { + if tf := strings.Count(sec.lower, t); tf > 0 { + w := 0.8 + // 扩展词命中且同节含 ASCII 标识符 → 视为等价强信号,升全权重 + // (探针② 实测:「部署时序照旧:停先 Go 后 Rust」行需按全词计分 + // 才能压过 INDEX 目录页的裸词面共现) + if len(ascii) > 0 && containsAnyMatched(matched, ascii) { + w = 1.0 + } + score += w * bm(tf, bmIDF(expandedDF[t]), secLen) + matched = append(matched, "~"+t) // 前缀标扩展命中 + } + } + if len(matched) == 0 { + continue + } + // 单字兜底通道:bigram 在语料里是碎片(如「启动顺序」实际文档写「时序」) + // 时,内容单字以 0.6 权重补召回(停用字已滤)。 + for _, r := range queryUnigrams { + tf := strings.Count(sec.lower, r) + if tf > 0 { + score += 0.6 * bm(tf, bmIDF(unigramDF[r]), secLen) + } + } + // SKILL.md = 人写权威综述(references 是案底),同分场景给 15% 先验 + if sec.isSkillMd { + score *= 1.15 + } + if len(ascii) > 0 && !containsAnyMatched(matched, ascii) { + // 查询含 ASCII 标识符而本节一个都不含 → 视为未命中该标识符语境,减半 + score *= 0.5 + } + // 路径题名先验:文件名 = 作者自己标的主题。CJK 词经文件名对照表映射到 + // ASCII 路径 token(部署→deploy),文件名命中 +3(探针② 实测:目标文档 + // 正文只写「部署时序」,词面打不过 INDEX 目录页,靠文件名定主题)。 + // 反查表刻意小(只收 6 对,与 skillGlossary 同源维护)。 + { + pathKey := strings.ToLower(sec.path) + fileNameMap := map[string]string{"部署": "deploy", "重启": "restart", "启动": "start", + "缓存": "cache", "端口": "port", "健康": "health", "顺序": "order", "指标": "metric"} + for _, t := range append(append([]string{}, cjk...), expanded...) { + if tok, ok := fileNameMap[t]; ok && strings.Contains(pathKey, tok) { + score += 3.0 + break + } + } + } + hits = append(hits, hit{sec: sec, score: score, matched: matched}) + } + // 行级共现加权(只重算前 300 候选,成本可控):同一行内共现的查询词对数 + // 是「规则行」的强判别信号 —— AC 探针② 的目标行「部署时序照旧:停先 Go 后 + // Rust、起先 Rust 后 Go」= 4 词同行。长文散提不配和规则行同分。 + { + allTerms := append(append(append([]string{}, ascii...), cjk...), expanded...) + top := hits + if len(top) > 300 { + sort.SliceStable(top, func(i, j int) bool { return top[i].score > top[j].score }) + top = top[:300] + } + for i := range top { + best, sum := 0, 0 + for _, line := range strings.Split(top[i].sec.lower, "\n") { + c := 0 + for _, t := range allTerms { + if strings.Contains(line, t) { + c++ + } + } + if c >= 2 { + pairs := c * (c - 1) / 2 + if pairs > 10 { + pairs = 10 + } + if pairs > best { + best = pairs + } + sum += pairs + } + } + // 最佳行主导 + 少量「多处提及」尾部信号(防目录页靠行数刷分) + top[i].score += 0.8*float64(best) + 0.15*float64(sum-best) + } + } + sort.SliceStable(hits, func(i, j int) bool { return hits[i].score > hits[j].score }) + + // 每文件取最高分一节,取前 n 个文件 + seenPath := map[string]bool{} + for _, h := range hits { + if seenPath[h.sec.path] { + continue + } + seenPath[h.sec.path] = true + out = append(out, SkillSectionRef{ + Path: h.sec.path, + Snippet: skillSnippet(h.sec.lower, h.matched, ascii, cjk), + Matched: topMatched(h.matched, 8), + Score: h.score, + }) + if len(out) >= n { + break + } + } + return out +} + +func containsAnyMatched(matched, terms []string) bool { + for _, m := range matched { + for _, t := range terms { + if m == t { + return true + } + } + } + return false +} + +func topMatched(matched []string, n int) []string { + if len(matched) <= n { + return matched + } + return matched[:n] +} + +// skillSnippet 首个高权重命中词附近 ±100 rune 窗口,压平空白。 +func skillSnippet(lower string, matched, ascii, cjk []string) string { + pref := append(append([]string{}, ascii...), cjk...) + rs := []rune(lower) + pos := -1 + for _, t := range pref { + i := strings.Index(lower, t) + if i >= 0 { + // rune 下标近似:按字节 index 换 rune 数(正文已是小写无多字节大小写问题) + pos = len([]rune(lower[:i])) + break + } + } + if pos < 0 { + pos = 0 + } + start := pos - skillRefSnippetRunes/2 + if start < 0 { + start = 0 + } + end := start + skillRefSnippetRunes + if end > len(rs) { + end = len(rs) + start = end - skillRefSnippetRunes + if start < 0 { + start = 0 + } + } + snip := strings.Join(strings.Fields(string(rs[start:end])), " ") + return snip +} diff --git a/go/internal/api/routes/skillrefs_test.go b/go/internal/api/routes/skillrefs_test.go new file mode 100644 index 0000000..f1734e3 --- /dev/null +++ b/go/internal/api/routes/skillrefs_test.go @@ -0,0 +1,168 @@ +// B1 第二路 skill 检索回归(t_e3f5cb79 · AC-2) +// +// 层 1(离线 fixture):开关语义、形状 {path,snippet,matched}、分节命中、 +// 查询停用词(「有哪些」类疑问词不得参与打分 —— 否则全库疑问句霸榜)。 +// 层 2(真实语料探针,AC-2.3 ①②;③「淇县招商 memories top1 不变」属线上 +// 行为,由部署后原始输出闭合): +// +// ① q="织忆有哪些缓存层" ⇒ 命中文件正文含 RedisCache 或 L2Cache +// ② q="Go Rust 启动顺序" ⇒ 命中含「先 Go」的文件(references/zhiyi-deploy-and-metrics.md) +package routes + +import ( + "os" + "path/filepath" + "strings" + "testing" +) + +func resetSkillIdxForTest(t *testing.T) { + t.Helper() + skillIdxMu.Lock() + skillIdxCache = nil + skillIdxMu.Unlock() + t.Cleanup(func() { + skillIdxMu.Lock() + skillIdxCache = nil + skillIdxMu.Unlock() + }) +} + +func TestSkillRefsDisabledReturnsEmpty(t *testing.T) { + resetSkillIdxForTest(t) + t.Setenv("ZHIYI_RECALL_SKILLREFS", "") + if got := skillRefsForQuery("织忆有哪些缓存层", 5); got == nil || len(got) != 0 { + t.Fatalf("开关关必须返回非 nil 空切片(JSON=[]),实际 %#v", got) + } +} + +func TestSkillQueryTermsStopwords(t *testing.T) { + ascii, cjk := skillQueryTerms("织忆有哪些缓存层") + if len(ascii) != 0 { + t.Fatalf("纯中文查询不应有 ascii: %v", ascii) + } + want := map[string]bool{"织忆": true, "缓存": true, "存层": true} + for _, s := range cjk { + if !want[s] { + t.Fatalf("停用词漏网: %v (full=%v)", s, cjk) + } + } + for w := range want { + found := false + for _, s := range cjk { + if s == w { + found = true + } + } + if !found { + t.Fatalf("实词被误删: %q full=%v", w, cjk) + } + } + // ASCII token 不受停用词影响 + a2, _ := skillQueryTerms("RedisCache 的 TTL 怎么配") + if len(a2) != 2 || a2[0] != "rediscache" || a2[1] != "ttl" { + t.Fatalf("ascii terms 错误: %v", a2) + } +} + +func writeFixtureSkill(t *testing.T, dir, rel, content string) string { + t.Helper() + p := filepath.Join(dir, rel) + if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(p, []byte(content), 0o644); err != nil { + t.Fatal(err) + } + return p +} + +func TestSkillRefsFixtureShapeAndHit(t *testing.T) { + resetSkillIdxForTest(t) + dir := t.TempDir() + p1 := writeFixtureSkill(t, dir, "zhiyi/zhiyi/SKILL.md", + "---\nname: zhiyi\n---\n# 织忆\n\n## 现成缓存设施清单\n\n| 设施 | 位置 |\n|---|---|\n| `RedisCache` + `NewRedisCache(ttl)` | storage/redis.go |\n| `L2CacheBackend` + `redisL2Adapter` | storage/searchcache.go |\n\n## 无关段\n\n这里讲图谱 pruning 的宽限期。\n") + p2 := writeFixtureSkill(t, dir, "cooking/pancake.md", + "# 煎饼\n\n## 做法\n\n面糊醒 20 分钟。全库最常说的「有哪些」句式也写在这。\n") + + t.Setenv("ZHIYI_SKILLS_DIR", dir) + t.Setenv("ZHIYI_RECALL_SKILLREFS", "1") + + refs := skillRefsForQuery("织忆有哪些缓存层", 5) + if len(refs) == 0 { + t.Fatalf("fixture 查询必须命中") + } + if refs[0].Path != p1 { + t.Fatalf("首位应命中 zhiyi SKILL.md,实际 %s", refs[0].Path) + } + for _, x := range refs { + if !strings.HasSuffix(x.Path, ".md") { + t.Fatalf("skill_refs 只能指向 md:%s", x.Path) + } + } + _ = p2 +} + +func TestSkillRefsRealCorpusProbes(t *testing.T) { + home, err := os.UserHomeDir() + if err != nil { + t.Skip("no home") + } + realDir := filepath.Join(home, ".hermes", "skills") + if fi, e := os.Stat(realDir); e != nil || !fi.IsDir() { + t.Skipf("真实技能库不存在:%s", realDir) + } + resetSkillIdxForTest(t) + t.Setenv("ZHIYI_SKILLS_DIR", "") // 走默认真实目录 + t.Setenv("ZHIYI_RECALL_SKILLREFS", "1") + + // 探针① + refs := skillRefsForQuery("织忆有哪些缓存层", 5) + if len(refs) == 0 { + t.Fatalf("探针① skill_refs 为空") + } + found := false + for _, r := range refs { + raw, e := os.ReadFile(r.Path) + if e != nil { + continue + } + if strings.Contains(string(raw), "RedisCache") || strings.Contains(string(raw), "L2Cache") { + found = true + t.Logf("探针① 命中:%s matched=%v", r.Path, r.Matched) + break + } + } + if !found { + t.Fatalf("探针① top3 中没有含 RedisCache/L2Cache 的文件:%v", pathsOf(refs)) + } + + // 探针② + refs = skillRefsForQuery("Go Rust 启动顺序", 5) + if len(refs) == 0 { + t.Fatalf("探针② skill_refs 为空") + } + found = false + for _, r := range refs { + raw, e := os.ReadFile(r.Path) + if e != nil { + continue + } + if strings.Contains(string(raw), "先 Go") || strings.Contains(string(raw), "先Go") { + found = true + t.Logf("探针② 命中:%s matched=%v", r.Path, r.Matched) + break + } + } + if !found { + t.Fatalf("探针② top3 中没有含「先 Go」的文件:%v", pathsOf(refs)) + } +} + +func pathsOf(refs []SkillSectionRef) []string { + out := make([]string, 0, len(refs)) + for _, r := range refs { + out = append(out, r.Path) + } + return out +} diff --git a/go/internal/distill/conflict_gate.go b/go/internal/distill/conflict_gate.go index 9baa154..248025c 100644 --- a/go/internal/distill/conflict_gate.go +++ b/go/internal/distill/conflict_gate.go @@ -15,12 +15,13 @@ // (四修判据,回归 conflict_scope_test.go),不在本文件重复实现。 // // 设计纪律: -// · 零新依赖(stdlib + internal/governance,无环:governance 只 import metrics)。 -// · 纯函数、无 IO/LLM/时钟 —— 任何来源(rule/llm/注入 judge)的 CONFLICT-MARK -// 都必须在 JudgeWriteOp 出口过这道门;不过门降级 UPDATE(sim≥更新阈值)或 ADD。 -// · 宁漏勿误:解析不出 = false;值类型不同 = 不可比 = false; -// 值带路径/斜杠等复合形态(如 `union=0/1`)= 拒绝解析(否则与 `union=1` -// 误配成「不同取值」——24 条存量回归里真实存在这一对,实测必须 0 真矛盾)。 +// +// · 零新依赖(stdlib + internal/governance,无环:governance 只 import metrics)。 +// · 纯函数、无 IO/LLM/时钟 —— 任何来源(rule/llm/注入 judge)的 CONFLICT-MARK +// 都必须在 JudgeWriteOp 出口过这道门;不过门降级 UPDATE(sim≥更新阈值)或 ADD。 +// · 宁漏勿误:解析不出 = false;值类型不同 = 不可比 = false; +// 值带路径/斜杠等复合形态(如 `union=0/1`)= 拒绝解析(否则与 `union=1` +// 误配成「不同取值」——24 条存量回归里真实存在这一对,实测必须 0 真矛盾)。 package distill import (