feat(kb-migrate): 存量知识库目录名迁移工具 + 启动期只报告

背景:旧版 Add 整串 sanitize 名字、逐段 sanitize 建目录,留下 tech/_go_/note、
Tech/Upper、a/b with space 这类「知识名与盘上目录不一致」的目录。修复后
normalizeName 要求二者逐字一致,故需一次性改名。

- 迁移逻辑放在 internal/knowledge/migrate_names.go(PlanMigration/
  ApplyMigration),CLI 与 homed 启动**共用同一份实现**,避免口径漂移。
- 三条硬约束:
  1. 默认只报告(-apply 才真改名)—— 批量 os.Rename 不可逆。
  2. 检出目标名冲突(两条迁到同一目标 / 目标已存在)则**整批拒绝**,
     不做部分迁移:半迁移状态比不迁移更难收拾。
  3. 逐条失败不中断,最后统一报告;执行前重查冲突(计划生成与执行之间
     可能有人改过盘上状态),并校验目标不越出知识根。
- homed 启动在 initKnowledgeStore **之前**调 initKnowledgeMigration:改名后
  扫盘一次到位,避免先以旧名建索引再改名造成内存键与盘上目录短暂不一致。
  defaultApply=false ⇒ 启动只扫描+报告+打印可执行命令行,不替人决定。
  单次改名上限 200 条,防失控目录规模拖住启动。

实测:报告模式零改动;冲突场景整批拒绝且盘上原封不动;迁移后 Store
正确载入 4 条并可按规范名逐条删除。
This commit is contained in:
JianFeeeee
2026-09-26 11:37:22 +08:00
parent cc353765d6
commit d10ab3fbf0
3 changed files with 158 additions and 0 deletions

View File

@ -378,6 +378,61 @@ func initKnowledgeStore(cfg *types.Config) *knowledge.Store {
return ks
}
// initKnowledgeMigration 在知识库扫盘**之前**把存量目录名规范化。
//
// 为何不靠 Store 内部自己做:规范名是「内存键 + 盘上目录 + LLM 可见名字」
// 三者必须逐字一致,而磁盘重命名属于有破坏性的副作用,应该在 store 扫盘
// 之前、在明确的边界上一次性做完,而不是散在 Store 的初始化路径里。
//
// 为何默认只报告:os.Rename 不可逆,批量重命名生产数据必须由人确认。
// 需要真正迁移时用 homed-kb-migrate -apply(或把下面 defaultApply 打开)。
//
// 本函数体同样遵守 bootstrap 的平移原则。
func initKnowledgeMigration(cfg *types.Config) {
root := filepath.Join(cfg.Daemon.DataDir, "knowledge")
const (
// defaultApply = false ⇒ 启动时只扫描并报告,不改名。
defaultApply = false
// maxRenamePerRun 限制单次重命名数:给失控的目录规模设一个上限,
// 避免启动阶段被一次大迁移拖住。
maxRenamePerRun = 200
)
items, err := knowledge.PlanMigration(root)
if err != nil {
log.Printf("[homed] 知识库迁移扫描失败(跳过): %v", err)
return
}
need, illegal := 0, 0
for _, it := range items {
if it.Illegal {
illegal++
} else if it.NewName != "" {
need++
}
}
if need == 0 && illegal == 0 {
return
}
if illegal > 0 {
log.Printf("[homed] 知识库迁移:%d 条名称非法(含 .. / 点段 / 隐藏段),写入与删除均已拒绝,需人工处理", illegal)
}
if need == 0 {
return
}
log.Printf("[homed] 知识库迁移:%d/%d 条目录名待规范化(例:%s → %s)", need, len(items),
items[0].OldName, items[0].NewName)
if !defaultApply {
log.Printf("[homed] 知识库迁移:当前为只报告模式。确认清单后执行:homed-kb-migrate -root %s -apply", root)
return
}
if need > maxRenamePerRun {
log.Printf("[homed] 知识库迁移:需改名 %d 条超过单次上限 %d,本次只处理前 %d 条",
need, maxRenamePerRun, maxRenamePerRun)
}
applied, failed := knowledge.ApplyMigration(root, items, maxRenamePerRun)
log.Printf("[homed] 知识库迁移完成:成功 %d,失败 %d", applied, failed)
}
// loadPersonality 按「个人文件 > 配置项」的优先级解析人格内容,并对腐坏内容告警。
//
// 本函数体是 main() 里对应启动阶段的整块平移:语句、日志文本、错误语义不变,