From bf3dc0f7ad9207c6ae941e049ab8aa7aafe4d1c0 Mon Sep 17 00:00:00 2001
From: ax_rd <ax_rd@aisim.cn>
Date: Thu, 03 Sep 2026 08:34:55 +0800
Subject: [PATCH] docs: 对标CodeGraph增强实施计划（10任务）+ go.env构建参数固化
---
docs/superpowers/plans/2026-09-03-kb-cli-codegraph-alignment.md | 2455 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 2,455 insertions(+), 0 deletions(-)
diff --git a/docs/superpowers/plans/2026-09-03-kb-cli-codegraph-alignment.md b/docs/superpowers/plans/2026-09-03-kb-cli-codegraph-alignment.md
new file mode 100644
index 0000000..63e1163
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-03-kb-cli-codegraph-alignment.md
@@ -0,0 +1,2455 @@
+# kb-cli 对标 CodeGraph 增强 实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 按 spec `docs/superpowers/specs/2026-09-03-kb-cli-codegraph-alignment-design.md` 实现 kb-cli 的 RWR 图排序、CJK 混合检索、增量同步、悬空双链自动补全、explore 命令。
+
+**Architecture:** SQLite(WAL) 单库存储，schema v2 迁移加列（aliases/status/provenance/文件指纹）；FTS5 改 external-content + 触发器；搜索 = FTS(ASCII 词) + LIKE(CJK 词) 双通道 → RWR 图质量 → min-max 双信号加权；索引改为 (size, mtime, sha256) 对账增量同步；wikilink 解析失败入 unresolved_links 表，新节点入库时自动重试。
+
+**Tech Stack:** Go 1.22.2, mattn/go-sqlite3 (FTS5), cobra, yaml.v3
+
+## Global Constraints
+
+- **构建标志（铁律）**：`CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm"`——本机 gcc 下 go-sqlite3 自带 amalgamation 链接 libm 失败导致 FTS5 编译失败；系统 libsqlite3 (3.45.1) 原生含 FTS5，加此两参数后全部测试通过。已存于 `go.env`，Makefile 必须固化
+- 不新增第三方依赖（stdlib + go.mod 现有依赖）
+- 注释/错误信息用中文，与现有代码风格一致
+- 每个任务 TDD：先写失败测试 → 跑失败 → 最小实现 → 跑通过 → commit
+- 测试命令模板：`CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"`
+- 现有代码约定：`nodes.path` UNIQUE；虚拟节点（tag/entity）ID 从 1000000 起；边表 `UNIQUE(from_node, to_node, relation, label)`
+- spec 全文在 `docs/superpowers/specs/2026-09-03-kb-cli-codegraph-alignment-design.md`，本计划与其冲突时以 spec 为准
+
+**实测背景（计划依据）：**
+- 真实库 `~/rag-lpg-obsidian`（458 个 .md）上 `search 补气` 只返回 1 条——FTS5 unicode61 把连续中文当整串单 token，`MATCH '补气'` 匹配不到"电子秤补气失败"；而 `LIKE '%补气%'` 命中 16 条 content + 1 条 title。**CJK 词必须走 LIKE 通道**
+- trigram tokenizer 实测：多字符 CJK 词部分可用（"红绿闪"命中）但单字符（"秤"）不命中，且改变现有 FTS 行为面太大——不采用，保持 unicode61
+
+---
+
+### Task 1: 构建环境固化 + Schema v2 迁移
+
+**Files:**
+- Create: `internal/index/migrations.go`
+- Create: `internal/index/migrations_test.go`
+- Modify: `internal/index/sqlite.go:48-87`（initTables）
+- Modify: `internal/index/fts.go:18-37`（CreateFTS/PopulateFTS）
+- Create: `Makefile`
+- Modify: `go.env`（已存在，确认内容）
+
+**Interfaces:**
+- Consumes: 现有 `Store.Open`
+- Produces: `func (s *Store) migrate() error`（Open 时自动调用）；v2 后 `nodes` 表含列：`aliases TEXT, status TEXT, size INTEGER, mtime INTEGER, content_hash TEXT`；`edges` 表含列 `provenance TEXT`；新表 `unresolved_links(id, from_node, link_text, name_tail, status, created_at, last_attempt)` 与 `schema_versions`；`nodes_fts` 为 external-content 虚拟表（title, content, tags, aliases）带增删改触发器
+
+- [ ] **Step 1: 固化构建标志（Makefile）**
+
+```makefile
+# Makefile
+CGO_CFLAGS := -DSQLITE_ENABLE_FTS5
+CGO_LDFLAGS := -lm
+
+.PHONY: build test clean
+
+build:
+ CGO_CFLAGS="$(CGO_CFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" go build -o kb-cli .
+
+test:
+ CGO_CFLAGS="$(CGO_CFLAGS)" CGO_LDFLAGS="$(CGO_LDFLAGS)" go test ./... 2>&1 | grep -v "no test files"
+
+clean:
+ rm -f kb-cli
+```
+
+- [ ] **Step 2: 写迁移失败测试**
+
+`internal/index/migrations_test.go`：
+
+```go
+package index
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+// newV1Store 手工构建一个 v1 schema 的老库（模拟迁移前状态）
+func newV1Store(t *testing.T) (*Store, string) {
+ t.Helper()
+ dbPath := filepath.Join(t.TempDir(), "kb-v1.db")
+ db, err := sql.Open("sqlite3", dbPath+"?_journal_mode=WAL")
+ if err != nil {
+ t.Fatal(err)
+ }
+ schema := `
+ CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+ CREATE TABLE nodes (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ path TEXT NOT NULL UNIQUE,
+ title TEXT, section TEXT, tags TEXT, entities TEXT, wikilinks TEXT,
+ content_fts TEXT,
+ created_at TEXT DEFAULT (datetime('now')),
+ updated_at TEXT DEFAULT (datetime('now')));
+ CREATE TABLE edges (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ from_node INTEGER NOT NULL, to_node INTEGER NOT NULL,
+ relation TEXT NOT NULL, label TEXT,
+ UNIQUE(from_node, to_node, relation, label));
+ `
+ if _, err := db.Exec(schema); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := db.Exec(`INSERT INTO nodes (path, title, tags, entities, wikilinks, content_fts)
+ VALUES ('FAQ/001-测试.md', '测试', '["a"]', '[]', '[]', '内容')`); err != nil {
+ t.Fatal(err)
+ }
+ return &Store{db: db}, dbPath
+}
+
+func TestMigrateV1ToV2(t *testing.T) {
+ store, dbPath := newV1Store(t)
+ defer store.Close()
+
+ // 迁移前备份文件必须存在
+ if err := store.migrate(); err != nil {
+ t.Fatalf("migrate: %v", err)
+ }
+ if _, err := os.Stat(dbPath + ".bak"); err != nil {
+ t.Fatalf("备份文件不存在: %v", err)
+ }
+
+ // v2 列必须存在
+ cols := store.nodeColumns(t)
+ for _, want := range []string{"aliases", "status", "size", "mtime", "content_hash"} {
+ if !cols[want] {
+ t.Errorf("nodes 缺列 %s", want)
+ }
+ }
+ if !store.edgeHasProvenance(t) {
+ t.Error("edges 缺 provenance 列")
+ }
+ if !store.tableExists(t, "unresolved_links") {
+ t.Error("缺 unresolved_links 表")
+ }
+
+ // 数据保留
+ var title string
+ if err := store.db.QueryRow(`SELECT title FROM nodes WHERE path='FAQ/001-测试.md'`).Scan(&title); err != nil {
+ t.Fatal(err)
+ }
+ if title != "测试" {
+ t.Errorf("迁移丢数据: %s", title)
+ }
+}
+
+func TestMigrateIdempotent(t *testing.T) {
+ store, _ := newV1Store(t)
+ defer store.Close()
+ if err := store.migrate(); err != nil {
+ t.Fatalf("第一次: %v", err)
+ }
+ if err := store.migrate(); err != nil {
+ t.Fatalf("第二次(幂等): %v", err)
+ }
+}
+
+func TestNewDBIsV2(t *testing.T) {
+ dbPath := filepath.Join(t.TempDir(), "kb-v2.db")
+ store, err := Open(dbPath)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer store.Close()
+ if !store.edgeHasProvenance(t) {
+ t.Error("新建库应为 v2 schema")
+ }
+}
+
+// 测试辅助：列检查
+func (s *Store) nodeColumns(t *testing.T) map[string]bool {
+ t.Helper()
+ rows, err := s.db.Query(`SELECT name FROM pragma_table_info('nodes')`)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer rows.Close()
+ m := map[string]bool{}
+ for rows.Next() {
+ var name string
+ rows.Scan(&name)
+ m[name] = true
+ }
+ return m
+}
+
+func (s *Store) edgeHasProvenance(t *testing.T) bool {
+ t.Helper()
+ var n int
+ s.db.QueryRow(`SELECT COUNT(*) FROM pragma_table_info('edges') WHERE name='provenance'`).Scan(&n)
+ return n > 0
+}
+
+func (s *Store) tableExists(t *testing.T, name string) bool {
+ t.Helper()
+ var n int
+ s.db.QueryRow(`SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?`, name).Scan(&n)
+ return n > 0
+}
+```
+
+注意：测试文件顶部需 `import "database/sql"`。
+
+- [ ] **Step 3: 跑测试确认失败**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -run TestMigrate -v`
+Expected: FAIL — `store.migrate undefined`
+
+- [ ] **Step 4: 实现 migrations.go**
+
+`internal/index/migrations.go`：
+
+```go
+package index
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+)
+
+const currentSchemaVersion = 2
+
+// migrate 幂等的 schema 升级：v1 → v2。
+// v2 变更：nodes 加 aliases/status/size/mtime/content_hash 列；
+// edges 加 provenance 列；新建 unresolved_links、schema_versions 表；
+// nodes_fts 改 external-content + 触发器。迁移前自动备份 .db 文件。
+func (s *Store) migrate() error {
+ // 读当前版本
+ var version int
+ err := s.db.QueryRow(`SELECT value FROM schema_versions WHERE key='version'`).Scan(&version)
+ if err != nil && version == 0 {
+ // 首次：schema_versions 表可能不存在
+ version = 1
+ }
+ if version >= currentSchemaVersion {
+ return nil
+ }
+
+ // 备份
+ if err := s.backupDB(); err != nil {
+ return fmt.Errorf("备份失败: %w", err)
+ }
+
+ // v1 → v2
+ if err := s.migrateV1toV2(); err != nil {
+ return fmt.Errorf("v1→v2 迁移失败: %w", err)
+ }
+ return nil
+}
+
+func (s *Store) backupDB() error {
+ // dbPath 从 DSN 提取：DSN 形如 <path>?_journal_mode=WAL
+ for _, row := range s.db.QueryRow(`PRAGMA database_list`).Rows() {
+ }
+ // 简化：Open 时把 dbPath 存到 Store
+ if s.dbPath == "" {
+ return nil // 无路径信息时跳过备份（测试场景）
+ }
+ dst := s.dbPath + ".bak"
+ if _, err := os.Stat(dst); err == nil {
+ return nil // 已有备份
+ }
+ data, err := os.ReadFile(s.dbPath)
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(dst, data, 0644)
+}
+
+func (s *Store) migrateV1toV2() error {
+ // 1. schema_versions 表
+ if _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS schema_versions (
+ key TEXT PRIMARY KEY, value TEXT NOT NULL)`); err != nil {
+ return err
+ }
+ if _, err := s.db.Exec(`INSERT OR REPLACE INTO schema_versions VALUES ('version', '2')`); err != nil {
+ return err
+ }
+
+ // 2. nodes 加列（逐列检查，幂等）
+ for _, col := range []struct{ name, def string }{
+ {"aliases", "ALTER TABLE nodes ADD COLUMN aliases TEXT"},
+ {"status", "ALTER TABLE nodes ADD COLUMN status TEXT"},
+ {"size", "ALTER TABLE nodes ADD COLUMN size INTEGER"},
+ {"mtime", "ALTER TABLE nodes ADD COLUMN mtime INTEGER"},
+ {"content_hash", "ALTER TABLE nodes ADD COLUMN content_hash TEXT"},
+ } {
+ if !s.nodeColumnExists(col.name) {
+ if _, err := s.db.Exec(col.def); err != nil {
+ return fmt.Errorf("加列 %s 失败: %w", col.name, err)
+ }
+ }
+ }
+
+ // 3. edges 加 provenance 列
+ if !s.edgeColumnExists("provenance") {
+ if _, err := s.db.Exec(`ALTER TABLE edges ADD COLUMN provenance TEXT`); err != nil {
+ return fmt.Errorf("edges 加 provenance 失败: %w", err)
+ }
+ }
+
+ // 4. unresolved_links 表
+ if _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS unresolved_links (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ from_node INTEGER NOT NULL,
+ link_text TEXT NOT NULL,
+ name_tail TEXT NOT NULL,
+ status TEXT NOT NULL DEFAULT 'pending',
+ created_at TEXT DEFAULT (datetime('now')),
+ last_attempt TEXT)`); err != nil {
+ return err
+ }
+ if _, err := s.db.Exec(`CREATE INDEX IF NOT EXISTS idx_unresolved_tail
+ ON unresolved_links(name_tail) WHERE status='failed'`); err != nil {
+ return err
+ }
+
+ // 5. FTS 改 external-content：删旧表重建 + 触发器 + 重灌
+ if _, err := s.db.Exec(`DROP TABLE IF EXISTS nodes_fts`); err != nil {
+ return err
+ }
+ if err := s.CreateFTS(); err != nil {
+ return err
+ }
+ return s.PopulateFTS()
+}
+
+// nodeColumnExists / edgeColumnExists 幂等检查
+func (s *Store) nodeColumnExists(name string) bool {
+ var n int
+ s.db.QueryRow(`SELECT COUNT(*) FROM pragma_table_info('nodes') WHERE name=?`, name).Scan(&n)
+ return n > 0
+}
+
+func (s *Store) edgeColumnExists(name string) bool {
+ var n int
+ s.db.QueryRow(`SELECT COUNT(*) FROM pragma_table_info('edges') WHERE name=?`, name).Scan(&n)
+ return n > 0
+}
+```
+
+- [ ] **Step 5: 改 Store 结构存 dbPath + Open 调 migrate**
+
+`internal/index/sqlite.go` 修改：
+
+```go
+// Store SQLite 存储层
+type Store struct {
+ db *sql.DB
+ dbPath string
+}
+
+func Open(dbPath string) (*Store, error) {
+ dir := filepath.Dir(dbPath)
+ if err := os.MkdirAll(dir, 0755); err != nil {
+ return nil, fmt.Errorf("创建目录失败: %w", err)
+ }
+ db, err := sql.Open("sqlite3", dbPath+"?_journal_mode=WAL")
+ if err != nil {
+ return nil, fmt.Errorf("打开数据库失败: %w", err)
+ }
+ s := &Store{db: db, dbPath: dbPath}
+ if err := s.initTables(); err != nil {
+ db.Close()
+ return nil, err
+ }
+ if err := s.migrate(); err != nil {
+ db.Close()
+ return nil, err
+ }
+ return s, nil
+}
+```
+
+`initTables` 的 v1 建表语句保留（全新库先建 v1 再被 migrate 升到 v2，幂等）。
+
+- [ ] **Step 6: 改 fts.go 为 external-content + 触发器**
+
+`internal/index/fts.go` 替换 CreateFTS/PopulateFTS：
+
+```go
+// CreateFTS 创建 FTS5 虚拟表（external-content 模式，由触发器增量维护）
+func (s *Store) CreateFTS() error {
+ _, err := s.db.Exec(`
+ CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+ title, content, tags, aliases,
+ content='nodes', content_rowid='id'
+ )`)
+ if err != nil {
+ return err
+ }
+ // 触发器：nodes 的增删改同步维护 FTS
+ triggers := []string{
+ `CREATE TRIGGER IF NOT EXISTS nodes_fts_ai AFTER INSERT ON nodes BEGIN
+ INSERT INTO nodes_fts(rowid, title, content, tags, aliases)
+ VALUES (new.id, new.title, new.content_fts, new.tags, new.aliases);
+ END`,
+ `CREATE TRIGGER IF NOT EXISTS nodes_fts_ad AFTER DELETE ON nodes BEGIN
+ INSERT INTO nodes_fts(nodes_fts, rowid, title, content, tags, aliases)
+ VALUES ('delete', old.id, old.title, old.content_fts, old.tags, old.aliases);
+ END`,
+ `CREATE TRIGGER IF NOT EXISTS nodes_fts_au AFTER UPDATE ON nodes BEGIN
+ INSERT INTO nodes_fts(nodes_fts, rowid, title, content, tags, aliases)
+ VALUES ('delete', old.id, old.title, old.content_fts, old.tags, old.aliases);
+ INSERT INTO nodes_fts(rowid, title, content, tags, aliases)
+ VALUES (new.id, new.title, new.content_fts, new.tags, new.aliases);
+ END`,
+ }
+ for _, t := range triggers {
+ if _, err := s.db.Exec(t); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+// PopulateFTS 全量重灌 FTS（external-content 模式专用语法）
+func (s *Store) PopulateFTS() error {
+ _, err := s.db.Exec(`INSERT INTO nodes_fts(nodes_fts) VALUES('rebuild')`)
+ return err
+}
+```
+
+- [ ] **Step 7: 全量测试**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"`
+Expected: 全部 PASS（含迁移测试 3 个 + 既有 FTS/search 测试）
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add Makefile go.env internal/index/migrations.go internal/index/migrations_test.go internal/index/sqlite.go internal/index/fts.go
+git commit -m "feat: schema v2 迁移（aliases/status/文件指纹/provenance/unresolved_links + FTS external-content）+ Makefile 固化 FTS5 构建标志"
+```
+
+---
+
+### Task 2: 增量对账（reconcile）
+
+**Files:**
+- Create: `internal/index/reconcile.go`
+- Create: `internal/index/reconcile_test.go`
+- Modify: `internal/vault/scanner.go`（新增 ScanVaultStat 只 stat 不解析）
+- Modify: `internal/vault/parser.go`（Frontmatter 加 Status 字段）
+- Modify: `internal/graph/model.go`（Node 加 Status/Aliases/Size/Mtime/ContentHash 字段）
+- Modify: `internal/index/sqlite.go`（InsertNode 写新列 + UpsertNode + DeleteNode）
+- Modify: `cmd/rebuild.go`（rebuildIndex 改走对账路径 + --force 全量）
+- Modify: `cmd/index.go`（index build 默认增量，加 --force flag；index gc 保留）
+- Delete: `internal/index/cache.go` 中 `NeedsRebuild` 函数（保留 GetGitCommit）
+
+**Interfaces:**
+- Consumes: Task 1 的 v2 schema（nodes 新列）
+- Produces:
+ - `func Reconcile(store *Store, vaultPath string) (*ReconcileResult, error)`
+ - `type ReconcileResult struct { Added, Modified, Deleted, Unchanged int }`
+ - `func QuickCheck(store *Store, vaultPath string) (bool, error)`（只 stat，返回"是否有差异"）
+ - `func (s *Store) UpsertNode(n *graph.Node) error`（按 path INSERT OR REPLACE，触发器自动维护 FTS）
+ - `func (s *Store) DeleteNode(path string) error`
+ - `func (s *Store) GetFileStats() (map[string]FileStat, error)`；`type FileStat struct { Path string; Size int64; Mtime int64; ContentHash string }`
+
+- [ ] **Step 1: vault 层——Status 提取 + ScanVaultStat**
+
+`internal/vault/parser.go` Frontmatter 加字段 + ParseFile 赋值：
+
+```go
+type Frontmatter struct {
+ Title string `yaml:"title"`
+ Tags []string `yaml:"tags"`
+ Entities []string `yaml:"entities"`
+ Aliases []string `yaml:"aliases"`
+ Status string `yaml:"status"`
+}
+```
+ParseFile 中解析成功后加：`meta.Status = fm.Status`；FileMeta 加 `Status string` 与 `Aliases []string` 字段（Aliases = fm.Aliases）。
+
+`internal/vault/scanner.go` 加（不改 ScanVault）：
+
+```go
+// FileStat 文件指纹（只 stat，不读内容）
+type FileStat struct {
+ Path string // 相对路径
+ Size int64
+ Mtime int64 // Unix 秒
+}
+
+// ScanVaultStat 扫描 .md 文件指纹清单（跳过隐藏目录和待审阅目录，与 ScanVault 一致）
+func ScanVaultStat(vaultPath string) ([]FileStat, error) {
+ var stats []FileStat
+ err := filepath.Walk(vaultPath, func(path string, info os.FileInfo, err error) error {
+ if err != nil {
+ return nil
+ }
+ if info.IsDir() {
+ if strings.HasPrefix(info.Name(), ".") && info.Name() != "." {
+ return filepath.SkipDir
+ }
+ if info.Name() == "待审阅" {
+ return filepath.SkipDir
+ }
+ return nil
+ }
+ if !strings.HasSuffix(path, ".md") {
+ return nil
+ }
+ relPath, _ := filepath.Rel(vaultPath, path)
+ stats = append(stats, FileStat{
+ Path: relPath,
+ Size: info.Size(),
+ Mtime: info.ModTime().Unix(),
+ })
+ return nil
+ })
+ return stats, err
+}
+```
+
+- [ ] **Step 2: 写对账失败测试**
+
+`internal/index/reconcile_test.go`：
+
+```go
+package index
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "github.com/aisim/kb-cli/internal/graph"
+ "github.com/aisim/kb-cli/internal/vault"
+)
+
+// setupVault 造一个含 1 个 .md 的临时 vault
+func setupVault(t *testing.T) string {
+ t.Helper()
+ dir := t.TempDir()
+ content := "---\ntitle: 测试文档\ntags: [t1]\n---\n正文提到 [[目标文档]] 和关键词补气\n"
+ if err := os.WriteFile(filepath.Join(dir, "FAQ", "001-测试文档.md"), []byte(content), 0644); err != nil {
+ // FAQ 目录需先建
+ }
+ return dir
+}
+
+func TestReconcileAdd(t *testing.T) {
+ dir := t.TempDir()
+ if err := os.MkdirAll(filepath.Join(dir, "FAQ"), 0755); err != nil {
+ t.Fatal(err)
+ }
+ content := "---\ntitle: 测试文档\ntags: [t1]\nstatus: 已解决\n---\n正文\n"
+ os.WriteFile(filepath.Join(dir, "FAQ", "001-测试文档.md"), []byte(content), 0644)
+
+ store, _ := Open(filepath.Join(t.TempDir(), "kb.db"))
+ defer store.Close()
+
+ res, err := Reconcile(store, dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if res.Added != 1 || res.Unchanged != 0 {
+ t.Errorf("新增场景: %+v", res)
+ }
+ var title, status string
+ store.db.QueryRow(`SELECT title, status FROM nodes WHERE path='FAQ/001-测试文档.md'`).Scan(&title, &status)
+ if title != "测试文档" || status != "已解决" {
+ t.Errorf("节点字段错误: %s / %s", title, status)
+ }
+}
+
+func TestReconcileModify(t *testing.T) {
+ dir := t.TempDir()
+ os.MkdirAll(filepath.Join(dir, "FAQ"), 0755)
+ p := filepath.Join(dir, "FAQ", "001-测试文档.md")
+ os.WriteFile(p, []byte("---\ntitle: 旧标题\n---\n旧内容\n"), 0644)
+
+ store, _ := Open(filepath.Join(t.TempDir(), "kb.db"))
+ defer store.Close()
+ Reconcile(store, dir)
+
+ // 修改内容（title 变新标题，内容加"补气"）
+ time.Sleep(1100 * time.Millisecond) // mtime 秒级精度，确保 mtime 变化
+ os.WriteFile(p, []byte("---\ntitle: 新标题\n---\n新内容补气\n"), 0644)
+
+ res, err := Reconcile(store, dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if res.Modified != 1 || res.Added != 0 {
+ t.Errorf("修改场景: %+v", res)
+ }
+ var title string
+ store.db.QueryRow(`SELECT title FROM nodes WHERE path='FAQ/001-测试文档.md'`).Scan(&title)
+ if title != "新标题" {
+ t.Errorf("标题未更新: %s", title)
+ }
+}
+
+func TestReconcileDelete(t *testing.T) {
+ dir := t.TempDir()
+ os.MkdirAll(filepath.Join(dir, "FAQ"), 0755)
+ p := filepath.Join(dir, "FAQ", "001-测试文档.md")
+ os.WriteFile(p, []byte("---\ntitle: 测试文档\n---\n内容\n"), 0644)
+
+ store, _ := Open(filepath.Join(t.TempDir(), "kb.db"))
+ defer store.Close()
+ Reconcile(store, dir)
+ os.Remove(p)
+
+ res, err := Reconcile(store, dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if res.Deleted != 1 {
+ t.Errorf("删除场景: %+v", res)
+ }
+ var n int
+ store.db.QueryRow(`SELECT COUNT(*) FROM nodes`).Scan(&n)
+ if n != 0 {
+ t.Errorf("节点未删净: %d", n)
+ }
+}
+
+func TestReconcileUnchanged(t *testing.T) {
+ dir := t.TempDir()
+ os.MkdirAll(filepath.Join(dir, "FAQ"), 0755)
+ os.WriteFile(filepath.Join(dir, "FAQ", "001-测试文档.md"),
+ []byte("---\ntitle: 测试文档\n---\n内容\n"), 0644)
+
+ store, _ := Open(filepath.Join(t.TempDir(), "kb.db"))
+ defer store.Close()
+ Reconcile(store, dir)
+
+ res, err := Reconcile(store, dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if res.Unchanged != 1 || res.Added != 0 || res.Modified != 0 {
+ t.Errorf("未变场景: %+v", res)
+ }
+}
+
+func TestQuickCheck(t *testing.T) {
+ dir := t.TempDir()
+ os.MkdirAll(filepath.Join(dir, "FAQ"), 0755)
+ os.WriteFile(filepath.Join(dir, "FAQ", "001-测试文档.md"),
+ []byte("---\ntitle: 测试文档\n---\n内容\n"), 0644)
+
+ store, _ := Open(filepath.Join(t.TempDir(), "kb.db"))
+ defer store.Close()
+ Reconcile(store, dir)
+
+ dirty, err := QuickCheck(store, dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if dirty {
+ t.Error("无差异时 QuickCheck 应 false")
+ }
+}
+```
+
+- [ ] **Step 3: 跑测试确认失败**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -run TestReconcile -v`
+Expected: FAIL — `undefined: Reconcile`
+
+- [ ] **Step 4: Store 新方法（sqlite.go 追加）**
+
+```go
+// FileStat 索引中的文件指纹
+type FileStat struct {
+ Path string
+ Size int64
+ Mtime int64
+ ContentHash string
+}
+
+// GetFileStats 返回所有已索引文件的指纹
+func (s *Store) GetFileStats() (map[string]FileStat, error) {
+ rows, err := s.db.Query(`SELECT path, size, mtime, content_hash FROM nodes`)
+ if err != nil {
+ return nil, err
+ }
+ defer rows.Close()
+ m := make(map[string]FileStat)
+ for rows.Next() {
+ var st FileStat
+ var hash sql.NullString
+ if err := rows.Scan(&st.Path, &st.Size, &st.Mtime, &hash); err != nil {
+ return nil, err
+ }
+ st.ContentHash = hash.String
+ m[st.Path] = st
+ }
+ return m, rows.Err()
+}
+
+// UpsertNode 按 path 插入或更新节点（触发器自动维护 FTS）
+func (s *Store) UpsertNode(n *graph.Node, size, mtime int64, contentHash string) error {
+ tagsJSON, _ := json.Marshal(n.Tags)
+ entitiesJSON, _ := json.Marshal(n.Entities)
+ wikilinksJSON, _ := json.Marshal(n.Wikilinks)
+ aliasesJSON, _ := json.Marshal(n.Aliases)
+ _, err := s.db.Exec(`
+ INSERT INTO nodes (path, title, section, tags, entities, wikilinks, aliases, status,
+ content_fts, size, mtime, content_hash)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT(path) DO UPDATE SET
+ title = excluded.title,
+ section = excluded.section,
+ tags = excluded.tags,
+ entities = excluded.entities,
+ wikilinks = excluded.wikilinks,
+ aliases = excluded.aliases,
+ status = excluded.status,
+ content_fts = excluded.content_fts,
+ size = excluded.size,
+ mtime = excluded.mtime,
+ content_hash = excluded.content_hash,
+ updated_at = datetime('now')`,
+ n.Path, n.Title, n.Section, string(tagsJSON), string(entitiesJSON),
+ string(wikilinksJSON), string(aliasesJSON), n.Status, n.Content, size, mtime, contentHash)
+ return err
+}
+
+// DeleteNode 按 path 删节点（级联删边），同时清该节点相关的 unresolved_links
+func (s *Store) DeleteNode(path string) error {
+ tx, err := s.db.Begin()
+ if err != nil {
+ return err
+ }
+ var id int64
+ if err := tx.QueryRow(`SELECT id FROM nodes WHERE path = ?`, path).Scan(&id); err != nil {
+ tx.Rollback()
+ return nil // 不存在，视为成功
+ }
+ if _, err := tx.Exec(`DELETE FROM edges WHERE from_node = ? OR to_node = ?`, id, id); err != nil {
+ tx.Rollback()
+ return err
+ }
+ if _, err := tx.Exec(`DELETE FROM unresolved_links WHERE from_node = ?`, id); err != nil {
+ tx.Rollback()
+ return err
+ }
+ if _, err := tx.Exec(`DELETE FROM nodes WHERE id = ?`, id); err != nil {
+ tx.Rollback()
+ return err
+ }
+ return tx.Commit()
+}
+
+// DeleteNodeEdges 只删某节点的边（保留节点行，用于"修改"场景重建边）
+func (s *Store) DeleteNodeEdges(nodeID int64) error {
+ _, err := s.db.Exec(`DELETE FROM edges WHERE from_node = ? OR to_node = ?`, nodeID, nodeID)
+ return err
+}
+```
+
+同时改 `InsertNode` 签名追加 `aliases/status/size/mtime/content_hash`（全量重建路径用），并同步 `graph.Node` 结构体加 `Aliases []string` 和 `Status string` 字段（Task 2 Step 1 已改 FileMeta，graph.Node 对齐）。
+
+- [ ] **Step 5: reconcile.go 实现**
+
+```go
+package index
+
+import (
+ "crypto/sha256"
+ "encoding/hex"
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+
+ "github.com/aisim/kb-cli/internal/graph"
+ "github.com/aisim/kb-cli/internal/vault"
+)
+
+// ReconcileResult 对账结果统计
+type ReconcileResult struct {
+ Added int
+ Modified int
+ Deleted int
+ Unchanged int
+}
+
+// Reconcile 增量对账：stat 比对 → 只对变更文件解析和写库
+func Reconcile(store *Store, vaultPath string) (*ReconcileResult, error) {
+ res := &ReconcileResult{}
+
+ // 1. vault 侧指纹
+ vaultStats, err := vault.ScanVaultStat(vaultPath)
+ if err != nil {
+ return nil, fmt.Errorf("扫描失败: %w", err)
+ }
+ dbStats, err := store.GetFileStats()
+ if err != nil {
+ return nil, fmt.Errorf("读取索引指纹失败: %w", err)
+ }
+
+ // 2. 分类
+ type change struct {
+ path string
+ stat vault.FileStat
+ known FileStat
+ }
+ var added, modified []change
+ for _, v := range vaultStats {
+ known, ok := dbStats[v.Path]
+ if !ok {
+ added = append(added, change{v.Path, v, FileStat{}})
+ continue
+ }
+ if v.Size == known.Size && v.Mtime == known.Mtime {
+ res.Unchanged++
+ continue
+ }
+ // size/mtime 变化 → sha256 二次确认
+ hash, err := fileHash(filepath.Join(vaultPath, v.Path))
+ if err != nil {
+ return nil, fmt.Errorf("哈希 %s 失败: %w", v.Path, err)
+ }
+ if known.ContentHash != "" && hash == known.ContentHash {
+ res.Unchanged++ // 内容没变（如 touch），只更新指纹
+ store.db.Exec(`UPDATE nodes SET size=?, mtime=? WHERE path=?`, v.Size, v.Mtime, v.Path)
+ continue
+ }
+ modified = append(modified, change{v.Path, v, known})
+ }
+ // 3. 删除
+ for path := range dbStats {
+ found := false
+ for _, v := range vaultStats {
+ if v.Path == path {
+ found = true
+ break
+ }
+ }
+ if !found {
+ if err := store.DeleteNode(path); err != nil {
+ return nil, err
+ }
+ res.Deleted++
+ }
+ }
+
+ // 4. 新增 + 修改：解析 → 写节点 → 重建该节点边
+ for _, c := range append(added, modified...) {
+ isNew := c.known.Path == ""
+ meta, err := vault.ParseFile(filepath.Join(vaultPath, c.path), c.path)
+ if err != nil {
+ return nil, fmt.Errorf("解析 %s 失败: %w", c.path, err)
+ }
+ hash, err := fileHash(filepath.Join(vaultPath, c.path))
+ if err != nil {
+ return nil, err
+ }
+ if isNew {
+ res.Added++
+ } else {
+ res.Modified++
+ }
+ if err := applyNode(store, vaultPath, meta, c.stat.Size, c.stat.Mtime, hash); err != nil {
+ return nil, err
+ }
+ }
+
+ // 5. 悬空链接重试（新增/修改节点可能让 failed 链接变可解析）
+ if res.Added+res.Modified > 0 {
+ store.RetryUnresolved() // 见 Task 4，此处先以空实现占位编译通过
+ }
+ return res, nil
+}
+
+func fileHash(path string) (string, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return "", err
+ }
+ sum := sha256.Sum256(data)
+ return hex.EncodeToString(sum[:]), nil
+}
+
+// applyNode 写节点 + 重建该节点的出边（tag/entity/wikilink）+ 悬空入表
+func applyNode(store *Store, vaultPath string, meta *vault.FileMeta, size, mtime int64, hash string) error {
+ n := &graph.Node{
+ Path: meta.Path, Title: meta.Title, Section: meta.Section,
+ Tags: meta.Tags, Entities: meta.Entities, Wikilinks: meta.Wikilinks,
+ Aliases: meta.Aliases, Status: meta.Status, Content: meta.Content,
+ }
+ if err := store.UpsertNode(n, size, mtime, hash); err != nil {
+ return err
+ }
+ var nodeID int64
+ if err := store.db.QueryRow(`SELECT id FROM nodes WHERE path=?`, meta.Path).Scan(&nodeID); err != nil {
+ return err
+ }
+ // 删旧边后重建出边
+ if err := store.DeleteNodeEdges(nodeID); err != nil {
+ return err
+ }
+ return store.buildNodeEdges(nodeID, meta)
+}
+
+// buildNodeEdges 为单个节点建出边；wikilink 解析失败入 unresolved_links
+func (s *Store) buildNodeEdges(nodeID int64, meta *vault.FileMeta) error {
+ // tag / entity 边（虚拟节点 ID 沿用 1000000+ 规则，按 label 查现有行避免重复）
+ for _, tag := range meta.Tags {
+ if err := s.insertTagEntityEdge(nodeID, "tag:"+tag, "tag", tag); err != nil {
+ return err
+ }
+ }
+ for _, entity := range meta.Entities {
+ if err := s.insertTagEntityEdge(nodeID, "entity:"+entity, "entity", entity); err != nil {
+ return err
+ }
+ }
+ // wikilink 边 + 悬空
+ for _, link := range meta.Wikilinks {
+ targetID, prov, ok := s.resolveWikilink(link)
+ if !ok {
+ tail := nameTail(link)
+ s.db.Exec(`INSERT INTO unresolved_links (from_node, link_text, name_tail, status)
+ VALUES (?, ?, ?, 'pending') ON CONFLICT DO NOTHING`, nodeID, link, tail)
+ continue
+ }
+ if err := s.InsertEdge(&graph.Edge{
+ FromNode: nodeID, ToNode: targetID,
+ Relation: "wikilink", Label: link, Provenance: prov,
+ }); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+// insertTagEntityEdge tag/entity 边（虚拟节点按 label 复用 ID）
+func (s *Store) insertTagEntityEdge(fromNode int64, key, relation, label string) error {
+ var virtualID int64
+ err := s.db.QueryRow(`SELECT to_node FROM edges WHERE relation=? AND label=? LIMIT 1`, relation, label).Scan(&virtualID)
+ if err != nil {
+ // 新虚拟节点：分配 ID = 1000000 + 行号（稳定：按 label 排序后的行号）
+ var maxID int64
+ s.db.QueryRow(`SELECT COALESCE(MAX(to_node), 1000000) FROM edges WHERE to_node >= 1000000 AND relation=?`, relation).Scan(&maxID)
+ virtualID = maxID + 1
+ }
+ return s.InsertEdge(&graph.Edge{FromNode: fromNode, ToNode: virtualID, Relation: relation, Label: label})
+}
+
+// resolveWikilink 解析 wikilink 目标，返回 (nodeID, provenance, ok)
+// provenance: exact = 标题或文件名精确匹配；fuzzy = 标题包含匹配
+func (s *Store) resolveWikilink(link string) (int64, string, bool) {
+ // 去锚点：[[标题|别名]] 取标题部分
+ if idx := strings.Index(link, "|"); idx >= 0 {
+ link = link[:idx]
+ }
+ var id int64
+ var title, path string
+ // 1. 标题精确
+ err := s.db.QueryRow(`SELECT id, title, path FROM nodes WHERE title = ? LIMIT 1`, link).Scan(&id, &title, &path)
+ if err == nil {
+ return id, "exact", true
+ }
+ // 2. 文件名精确（去 .md 和编号前缀）
+ rows, err := s.db.Query(`SELECT id, title, path FROM nodes`)
+ if err != nil {
+ return 0, "", false
+ }
+ defer rows.Close()
+ var fuzzyID int64
+ for rows.Next() {
+ var nid int64
+ var nTitle, nPath string
+ if err := rows.Scan(&nid, &nTitle, &nPath); err != nil {
+ return 0, "", false
+ }
+ base := filepath.Base(nPath)
+ base = strings.TrimSuffix(base, ".md")
+ if dash := strings.Index(base, "-"); dash >= 0 {
+ base = base[dash+1:]
+ }
+ if base == link || nTitle == link {
+ return nid, "exact", true
+ }
+ if fuzzyID == 0 && strings.Contains(nTitle, link) {
+ fuzzyID = nid
+ }
+ }
+ if fuzzyID != 0 {
+ return fuzzyID, "fuzzy", true
+ }
+ return 0, "", false
+}
+
+// nameTail 取 link 尾部用于重试匹配（去锚点修饰）
+func nameTail(link string) string {
+ if idx := strings.Index(link, "|"); idx >= 0 {
+ link = link[:idx]
+ }
+ return link
+}
+```
+
+注意：`resolveWikilink` 的全表扫描对 458 节点规模可接受；Task 4 的 RetryUnresolved 复用同一函数。`graph.Edge` 需加 `Provenance string` 字段，`InsertEdge` SQL 加 provenance 列。
+
+- [ ] **Step 6: retryUnresolved 空实现占位（Task 4 补全）**
+
+reconcile.go 底部：
+
+```go
+// RetryUnresolved 重试解析悬空链接（Task 4 补全完整实现）
+func (s *Store) RetryUnresolved() {}
+```
+
+- [ ] **Step 7: 改 cmd 层**
+
+`cmd/rebuild.go`：`rebuildIndex` 保留为全量路径（改名 `rebuildFull`），新增：
+
+```go
+// syncIndex 增量对账路径（index build 默认、search pre-flight 用）
+func syncIndex(store *index.Store) error {
+ res, err := index.Reconcile(store, vaultPath)
+ if err != nil {
+ return fmt.Errorf("增量同步失败: %w", err)
+ }
+ fmt.Fprintf(os.Stderr, "增量同步: 新增 %d / 修改 %d / 删除 %d / 未变 %d\n",
+ res.Added, res.Modified, res.Deleted, res.Unchanged)
+ if commit, err := index.GetGitCommit(vaultPath); err == nil {
+ store.SetMeta("git_commit", commit)
+ }
+ store.SetMeta("built_at", time.Now().Format(time.RFC3339))
+ return nil
+}
+```
+
+`cmd/index.go`：`indexBuildCmd` 加 `--force` bool flag；`runIndexBuild`：force → rebuildFull，默认 → syncIndex。
+
+`cmd/search.go`：pre-flight 从 `NeedsRebuild` 改为：
+
+```go
+dirty, err := index.QuickCheck(store, vaultPath)
+if err != nil {
+ return fmt.Errorf("索引状态检查失败: %w", err)
+}
+if dirty {
+ fmt.Fprintln(os.Stderr, "索引有变更，正在增量同步...")
+ if err := syncIndex(store); err != nil {
+ return fmt.Errorf("增量同步失败: %w", err)
+ }
+}
+```
+
+`internal/index/cache.go`：删除 `NeedsRebuild` 函数（`GetGitCommit` 保留），文件重命名保持 cache.go 不改名（减少 diff）。
+
+- [ ] **Step 8: QuickCheck 实现（reconcile.go）**
+
+```go
+// QuickCheck 只 stat 比对（不读内容不哈希），返回是否有差异
+func QuickCheck(store *Store, vaultPath string) (bool, error) {
+ vaultStats, err := vault.ScanVaultStat(vaultPath)
+ if err != nil {
+ return false, err
+ }
+ dbStats, err := store.GetFileStats()
+ if err != nil {
+ return false, err
+ }
+ if len(vaultStats) != len(dbStats) {
+ return true, nil
+ }
+ for _, v := range vaultStats {
+ known, ok := dbStats[v.Path]
+ if !ok || v.Size != known.Size || v.Mtime != known.Mtime {
+ return true, nil
+ }
+ }
+ return false, nil
+}
+```
+
+- [ ] **Step 9: 全量测试 + 编译**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files" && CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go build ./...`
+Expected: 全 PASS + 编译通过
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add internal/index/ internal/vault/ internal/graph/model.go cmd/
+git commit -m "feat: 增量对账同步（stat+sha256 比对，替代 commit hash 全量重建）"
+```
+
+---
+
+### Task 3: 边可信度 + 悬空链接表接入全量重建
+
+**Files:**
+- Modify: `internal/graph/model.go`（Edge 加 Provenance）
+- Modify: `internal/graph/builder.go`（BuildGraph 产出 provenance + Unresolved 列表）
+- Create: `internal/graph/builder_test.go`（provenance 用例）
+- Modify: `internal/index/sqlite.go`（InsertEdge 写 provenance；InsertUnresolved）
+- Modify: `cmd/rebuild.go`（全量重建写入 unresolved）
+
+**Interfaces:**
+- Consumes: Task 2 的 `resolveWikilink`（迁移为 graph 包共享函数 `graph.ResolveWikilink`，reconcile.go 改引用）
+- Produces:
+ - `graph.Edge{Provenance string}`（"exact"|"fuzzy"|"tag"|"entity"）
+ - `graph.BuildGraph(files []*vault.FileMeta) (*Graph, []*UnresolvedLink)`
+ - `type UnresolvedLink struct { FromNode int64; LinkText string; NameTail string }`（FromNode 为 BuildGraph 内部 ID）
+ - `func (s *Store) InsertUnresolved(fromNode int64, linkText, nameTail string) error`
+
+- [ ] **Step 1: 失败测试——builder provenance**
+
+`internal/graph/builder_test.go`：
+
+```go
+package graph
+
+import (
+ "testing"
+
+ "github.com/aisim/kb-cli/internal/vault"
+)
+
+func TestBuildGraphProvenance(t *testing.T) {
+ files := []*vault.FileMeta{
+ {Path: "FAQ/001-补气失败.md", Title: "补气失败", Wikilinks: []string{"红绿闪", "不存在的链接"}},
+ {Path: "FAQ/002-红绿闪.md", Title: "红绿闪"},
+ {Path: "知识/003-称重原理.md", Title: "称重原理详解"}, // "称重原理" 是 "称重原理详解" 的子串 → fuzzy
+ }
+ files[0].Wikilinks = append(files[0].Wikilinks, "称重原理")
+
+ g, unresolved := BuildGraph(files)
+
+ // exact: 标题精确匹配
+ var exact, fuzzy int
+ for _, e := range g.Edges {
+ if e.Relation != "wikilink" {
+ continue
+ }
+ switch e.Provenance {
+ case "exact":
+ exact++
+ case "fuzzy":
+ fuzzy++
+ }
+ }
+ if exact != 1 || fuzzy != 1 {
+ t.Errorf("provenance 分布: exact=%d fuzzy=%d (want 1/1)", exact, fuzzy)
+ }
+ // 悬空链接
+ if len(unresolved) != 1 || unresolved[0].LinkText != "不存在的链接" {
+ t.Errorf("unresolved: %+v", unresolved)
+ }
+ if unresolved[0].NameTail != "不存在的链接" {
+ t.Errorf("name_tail: %s", unresolved[0].NameTail)
+ }
+}
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/graph/ -run TestBuildGraphProvenance -v`
+Expected: FAIL — `Provenance 未定义 / BuildGraph 返回值不匹配`
+
+- [ ] **Step 3: 实现**
+
+`internal/graph/model.go`：
+
+```go
+// Edge 图边（实体关系）
+type Edge struct {
+ FromNode int64 `json:"from_node"`
+ ToNode int64 `json:"to_node"`
+ Relation string `json:"relation"` // "tag" | "entity" | "wikilink"
+ Label string `json:"label"`
+ Provenance string `json:"provenance"` // "exact" | "fuzzy" | "tag" | "entity"
+}
+
+// UnresolvedLink 悬空 wikilink（未匹配到目标节点）
+type UnresolvedLink struct {
+ FromNode int64 // BuildGraph 内部节点 ID
+ LinkText string
+ NameTail string
+}
+```
+
+`internal/graph/builder.go`：`BuildGraph` 签名改 `func BuildGraph(files []*vault.FileMeta) (*Graph, []*UnresolvedLink)`；wikilink 匹配循环中：
+
+```go
+for _, n := range g.Nodes {
+ for _, link := range n.Wikilinks {
+ target, prov := matchWikilink(g.Nodes, link)
+ if target == nil {
+ unresolved = append(unresolved, &UnresolvedLink{
+ FromNode: n.ID, LinkText: link, NameTail: nameTail(link),
+ })
+ continue
+ }
+ g.Edges = append(g.Edges, &Edge{
+ FromNode: n.ID, ToNode: target.ID,
+ Relation: "wikilink", Label: link, Provenance: prov,
+ })
+ }
+}
+```
+
+`matchWikilink` 从现有 `matchesWikilink` 升级：
+
+```go
+// matchWikilink 返回 (目标节点, provenance)。exact = 标题/文件名精确；fuzzy = 标题包含
+func matchWikilink(nodes []*Node, link string) (*Node, string) {
+ // 去锚点
+ if idx := strings.Index(link, "|"); idx >= 0 {
+ link = link[:idx]
+ }
+ var fuzzy *Node
+ for _, node := range nodes {
+ if node.Title == link {
+ return node, "exact"
+ }
+ base := filepath.Base(node.Path)
+ base = strings.TrimSuffix(base, ".md")
+ if dash := strings.Index(base, "-"); dash >= 0 {
+ base = base[dash+1:]
+ }
+ if base == link {
+ return node, "exact"
+ }
+ if fuzzy == nil && strings.Contains(node.Title, link) {
+ fuzzy = node
+ }
+ }
+ if fuzzy != nil {
+ return fuzzy, "fuzzy"
+ }
+ return nil, ""
+}
+
+func nameTail(link string) string {
+ if idx := strings.Index(link, "|"); idx >= 0 {
+ link = link[:idx]
+ }
+ return link
+}
+```
+
+tag/entity 边追加 `Provenance: "tag"` / `"entity"`。
+
+`internal/index/sqlite.go` InsertEdge 改：
+
+```go
+func (s *Store) InsertEdge(e *graph.Edge) error {
+ _, err := s.db.Exec(`
+ INSERT OR IGNORE INTO edges (from_node, to_node, relation, label, provenance)
+ VALUES (?, ?, ?, ?, ?)`, e.FromNode, e.ToNode, e.Relation, e.Label, e.Provenance)
+ return err
+}
+
+// InsertUnresolved 悬空链接入表（幂等：同 from_node+link_text 不重复插）
+func (s *Store) InsertUnresolved(fromNode int64, linkText, nameTail string) error {
+ _, err := s.db.Exec(`
+ INSERT INTO unresolved_links (from_node, link_text, name_tail, status)
+ SELECT ?, ?, ?, 'pending'
+ WHERE NOT EXISTS (
+ SELECT 1 FROM unresolved_links WHERE from_node = ? AND link_text = ?)`,
+ fromNode, linkText, nameTail, fromNode, linkText)
+ return err
+}
+```
+
+`cmd/rebuild.go` 全量路径：`g, unresolved := graph.BuildGraph(files)`；节点写完后映射 ID 写 unresolved：
+
+```go
+for _, u := range unresolved {
+ fromID, ok := idMap[u.FromNode]
+ if !ok {
+ continue
+ }
+ if err := store.InsertUnresolved(fromID, u.LinkText, u.NameTail); err != nil {
+ return err
+ }
+}
+```
+
+`internal/index/reconcile.go`（Task 2 产物）：`buildNodeEdges` 中 wikilink 解析改调 `graph.ResolveWikilink`——为便于共享，Task 2 的 `resolveWikilink` 逻辑保留在 Store 上（DB 查询版），graph 包的是纯内存版，两者规则一致即可，不强制合并（避免跨包依赖 SQLite）。
+
+- [ ] **Step 4: 跑测试**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"`
+Expected: 全 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/graph/ internal/index/sqlite.go cmd/rebuild.go
+git commit -m "feat: wikilink 边可信度标注（exact/fuzzy）+ 悬空链接入 unresolved_links 表"
+```
+
+---
+
+### Task 4: 悬空链接自动补全（RetryUnresolved）
+
+**Files:**
+- Modify: `internal/index/reconcile.go`（RetryUnresolved 补全实现）
+- Create: `internal/index/reconcile_test.go` 追加测试（或新文件 `unresolved_test.go`）
+
+**Interfaces:**
+- Consumes: Task 3 的 `InsertUnresolved`、`resolveWikilink`（Store 版）
+- Produces: `func (s *Store) RetryUnresolved() (resolved int, error error)`——每次对账后调用
+
+- [ ] **Step 1: 失败测试**
+
+`internal/index/unresolved_test.go`：
+
+```go
+package index
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+)
+
+func TestRetryUnresolved(t *testing.T) {
+ dir := t.TempDir()
+ os.MkdirAll(filepath.Join(dir, "FAQ"), 0755)
+ os.WriteFile(filepath.Join(dir, "FAQ", "001-旧文档.md"),
+ []byte("---\ntitle: 旧文档\n---\n提到 [[补气失败]]\n"), 0644)
+
+ store, _ := Open(filepath.Join(t.TempDir(), "kb.db"))
+ defer store.Close()
+
+ Reconcile(store, dir)
+
+ // 验证悬空链接入表
+ var n int
+ store.db.QueryRow(`SELECT COUNT(*) FROM unresolved_links WHERE link_text='补气失败'`).Scan(&n)
+ if n != 1 {
+ t.Fatalf("悬空链接未入表: %d", n)
+ }
+
+ // 新文档入库：标题正好是 "补气失败"
+ os.WriteFile(filepath.Join(dir, "FAQ", "002-补气失败.md"),
+ []byte("---\ntitle: 补气失败\n---\n补气失败排查\n"), 0644)
+
+ res, err := Reconcile(store, dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if res.Added != 1 {
+ t.Fatalf("新增: %+v", res)
+ }
+
+ // 悬空链接应被解析：行删除 + 边建立
+ store.db.QueryRow(`SELECT COUNT(*) FROM unresolved_links WHERE link_text='补气失败'`).Scan(&n)
+ if n != 0 {
+ t.Errorf("悬空行未清除: %d", n)
+ }
+ store.db.QueryRow(`SELECT COUNT(*) FROM edges WHERE relation='wikilink' AND label='补气失败'`).Scan(&n)
+ if n != 1 {
+ t.Errorf("wikilink 边未建立: %d", n)
+ }
+ var prov string
+ store.db.QueryRow(`SELECT provenance FROM edges WHERE relation='wikilink' AND label='补气失败'`).Scan(&prov)
+ if prov != "exact" {
+ t.Errorf("补全边应为 exact: %s", prov)
+ }
+}
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -run TestRetryUnresolved -v`
+Expected: FAIL — RetryUnresolved 是空实现，悬空行不清除
+
+- [ ] **Step 3: 实现 RetryUnresolved**
+
+reconcile.go 替换空实现：
+
+```go
+// RetryUnresolved 重试解析悬空链接：用当前全部节点的标题/文件名去匹配 unresolved_links 的 name_tail。
+// 命中则建边（provenance 按匹配严格度）、删行。返回成功解析条数。
+func (s *Store) RetryUnresolved() (int, error) {
+ rows, err := s.db.Query(`SELECT id, from_node, link_text, name_tail FROM unresolved_links`)
+ if err != nil {
+ return 0, err
+ }
+ type pending struct {
+ id int64
+ fromNode int64
+ linkText string
+ tail string
+ }
+ var pendings []pending
+ for rows.Next() {
+ var p pending
+ if err := rows.Scan(&p.id, &p.fromNode, &p.linkText, &p.tail); err != nil {
+ rows.Close()
+ return 0, err
+ }
+ pendings = append(pendings, p)
+ }
+ rows.Close()
+ if len(pendings) == 0 {
+ return 0, nil
+ }
+
+ // 建匹配索引：标题/文件名(去编号) → nodeID，精确匹配优先
+ type matchInfo struct {
+ id int64
+ prov string
+ }
+ exactMap := make(map[string]matchInfo)
+ var fuzzyRows []struct {
+ id int64
+ title string
+ }
+ nrows, err := s.db.Query(`SELECT id, title, path FROM nodes`)
+ if err != nil {
+ return 0, err
+ }
+ for nrows.Next() {
+ var id int64
+ var title, path string
+ if err := nrows.Scan(&id, &title, &path); err != nil {
+ nrows.Close()
+ return 0, err
+ }
+ if _, ok := exactMap[title]; !ok {
+ exactMap[title] = matchInfo{id, "exact"}
+ }
+ base := filepath.Base(path)
+ base = strings.TrimSuffix(base, ".md")
+ if dash := strings.Index(base, "-"); dash >= 0 {
+ base = base[dash+1:]
+ }
+ if _, ok := exactMap[base]; !ok {
+ exactMap[base] = matchInfo{id, "exact"}
+ }
+ fuzzyRows = append(fuzzyRows, struct {
+ id int64
+ title string
+ }{id, title})
+ }
+ nrows.Close()
+
+ resolved := 0
+ for _, p := range pendings {
+ if info, ok := exactMap[p.tail]; ok {
+ // 建边
+ if err := s.InsertEdge(&graph.Edge{
+ FromNode: p.fromNode, ToNode: info.id,
+ Relation: "wikilink", Label: p.linkText, Provenance: info.prov,
+ }); err != nil {
+ return resolved, err
+ }
+ if _, err := s.db.Exec(`DELETE FROM unresolved_links WHERE id=?`, p.id); err != nil {
+ return resolved, err
+ }
+ resolved++
+ continue
+ }
+ // fuzzy：标题包含
+ for _, fr := range fuzzyRows {
+ if strings.Contains(fr.title, p.tail) {
+ if err := s.InsertEdge(&graph.Edge{
+ FromNode: p.fromNode, ToNode: fr.id,
+ Relation: "wikilink", Label: p.linkText, Provenance: "fuzzy",
+ }); err != nil {
+ return resolved, err
+ }
+ s.db.Exec(`DELETE FROM unresolved_links WHERE id=?`, p.id)
+ resolved++
+ break
+ }
+ }
+ }
+ return resolved, nil
+}
+```
+
+reconcile.go 需 import `github.com/aisim/kb-cli/internal/graph` 和 `strings`（已有）。
+
+- [ ] **Step 4: 跑测试**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -v 2>&1 | tail -20`
+Expected: 全 PASS（含 Task 2 的 5 个对账测试）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add internal/index/
+git commit -m "feat: 悬空双链自动补全（新文档入库后历史链接自动解析建边）"
+```
+
+---
+
+### Task 5: RWR 图排序 + CJK 混合检索 + 双信号加权
+
+**Files:**
+- Create: `internal/graph/rwr.go`
+- Create: `internal/graph/rwr_test.go`
+- Create: `internal/index/graphload.go`（RWR 邻接加载）
+- Modify: `internal/index/fts.go`（FTSSearch 拆 ASCII/CJK 双通道）
+- Modify: `internal/search/engine.go`（双信号加权 + status 降权）
+- Modify: `internal/search/scorer.go`（aliases 位置权重）
+- Modify: `cmd/search.go`（读 config 的 text_weight）
+- Modify: `internal/llm/client.go`（Config 加 Search/Explore 节）
+
+**Interfaces:**
+- Consumes: Task 3 的 provenance 边
+- Produces:
+ - `func RWR(seedIDs []int64, adj map[int64][]adjEdge, alpha float64) map[int64]float64`
+ - `type adjEdge struct { To int64; Weight float64 }`
+ - `func (s *Store) LoadRWRGraph(seedIDs []int64) (map[int64][]adjEdge, error)`（只加载种子可达子图内的边；wikilink exact=1.0 / fuzzy=0.5 / entity=1.0 / tag=0.5）
+ - `func (s *Store) KeywordSearch(keywords []string, limit int) ([]FTSResult, error)`（ASCII 走 FTS MATCH，CJK 走 LIKE 合并）
+ - `func search.ContainsCJK(s string) bool`
+
+- [ ] **Step 1: RWR 失败测试**
+
+`internal/graph/rwr_test.go`：
+
+```go
+package graph
+
+import "testing"
+
+func TestRWRConvergenceAndSeed(t *testing.T) {
+ // 图: A-B-C 链 + D 孤立
+ adj := map[int64][]adjEdge{
+ 1: {{2, 1}}, 2: {{1, 1}, {3, 1}}, 3: {{2, 1}}, 4: {{}},
+ }
+ r := RWR([]int64{1}, adj, 0.25)
+ if r[1] <= 0 {
+ t.Fatal("种子节点质量必须 > 0")
+ }
+ // 与种子连通的质量应高于孤立节点
+ if r[4] >= r[3] {
+ t.Errorf("孤立节点质量不应高于连通节点: r4=%f r3=%f", r[4], r[3])
+ }
+ // 归一化 [0,1]
+ for _, v := range r {
+ if v < 0 || v > 1 {
+ t.Errorf("质量未归一化: %f", v)
+ }
+ }
+}
+
+func TestRWRWeightedByProvenance(t *testing.T) {
+ // A -exact-> B, A -fuzzy-> C：B 的质量应高于 C
+ adj := map[int64][]adjEdge{
+ 1: {{2, 1.0}, {3, 0.5}},
+ 2: {{1, 1.0}},
+ 3: {{1, 0.5}},
+ }
+ r := RWR([]int64{1}, adj, 0.25)
+ if r[2] <= r[3] {
+ t.Errorf("exact 边节点质量应高于 fuzzy: r2=%f r3=%f", r[2], r[3])
+ }
+}
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/graph/ -run TestRWR -v`
+Expected: FAIL — `undefined: RWR`
+
+- [ ] **Step 3: 实现 rwr.go**
+
+```go
+package graph
+
+// adjEdge 带权邻接边
+type adjEdge struct {
+ To int64
+ Weight float64
+}
+
+// RWR Random-Walk-with-Restart（个性化 PageRank）：
+// 从种子集合出发在无向带权图上做 power iteration，restart 概率 alpha 回到种子。
+// 返回归一化到 [0,1] 的游走质量。确定性算法，无随机数。
+func RWR(seedIDs []int64, adj map[int64][]adjEdge, alpha float64) map[int64]float64 {
+ if len(seedIDs) == 0 {
+ return map[int64]float64{}
+ }
+ // 收集参与节点：种子 + 邻接可达
+ nodes := make(map[int64]bool)
+ for _, s := range seedIDs {
+ nodes[s] = true
+ }
+ for from := range adj {
+ nodes[from] = true
+ for _, e := range adj[from] {
+ nodes[e.To] = true
+ }
+ }
+ n := len(nodes)
+ if n == 0 {
+ return map[int64]float64{}
+ }
+ idx := make(map[int64]int, n)
+ ids := make([]int64, 0, n)
+ for id := range nodes {
+ idx[id] = len(ids)
+ ids = append(ids, id)
+ }
+
+ // 重启向量：种子均匀
+ r := make([]float64, n)
+ for _, s := range seedIDs {
+ if i, ok := idx[s]; ok {
+ r[i] = 1.0 / float64(len(seedIDs))
+ }
+ }
+
+ const maxIter = 50
+ const eps = 1e-6
+ newR := make([]float64, n)
+ for iter := 0; iter < maxIter; iter++ {
+ for i := range newR {
+ newR[i] = 0
+ }
+ // 游走传播：out[i] = sum(w_ij)
+ for i, id := range ids {
+ var total float64
+ for _, e := range adj[id] {
+ total += e.Weight
+ }
+ if total == 0 {
+ continue
+ }
+ for _, e := range adj[id] {
+ j, ok := idx[e.To]
+ if !ok {
+ continue
+ }
+ newR[j] += (1-alpha) * r[i] * e.Weight / total
+ }
+ }
+ // restart
+ for i := range newR {
+ newR[i] += alpha * r[i]
+ }
+ // 收敛判断
+ diff := 0.0
+ for i := range newR {
+ d := newR[i] - r[i]
+ if d < 0 {
+ d = -d
+ }
+ diff += d
+ }
+ r, newR = newR, r
+ if diff < eps {
+ break
+ }
+ }
+ // 归一化 [0,1]
+ maxV := 0.0
+ for _, v := range r {
+ if v > maxV {
+ maxV = v
+ }
+ }
+ out := make(map[int64]float64, n)
+ if maxV == 0 {
+ for _, id := range ids {
+ out[id] = 0
+ }
+ return out
+ }
+ for i, id := range ids {
+ out[id] = r[i] / maxV
+ }
+ return out
+}
+```
+
+- [ ] **Step 4: LoadRWRGraph（internal/index/graphload.go）**
+
+```go
+package index
+
+import (
+ "fmt"
+
+ "github.com/aisim/kb-cli/internal/graph"
+)
+
+// LoadRWRGraph 加载 RWR 邻接（无向、带权）。
+// 权重：wikilink exact=1.0 / fuzzy=0.5 / entity=1.0 / tag=0.5（tag 扇出大降权）。
+// 只加载与种子同连通域的边不可行（SQLite 无图查询），全量加载后 RWR 内部按种子收敛——
+// 458 节点 / ~2k 边规模下全量加载 <5ms，可接受。
+func (s *Store) LoadRWRGraph() (map[int64][]graph.adjEdge, error) {
+ rows, err := s.db.Query(`
+ SELECT from_node, to_node, relation, provenance FROM edges
+ WHERE relation IN ('wikilink', 'entity', 'tag')`)
+ if err != nil {
+ return nil, fmt.Errorf("加载边失败: %w", err)
+ }
+ defer rows.Close()
+ adj := make(map[int64][]graph.adjEdge)
+ add := func(from, to int64, w float64) {
+ adj[from] = append(adj[from], graph.adjEdge{To: to, Weight: w})
+ adj[to] = append(adj[to], graph.adjEdge{To: from, Weight: w})
+ }
+ for rows.Next() {
+ var from, to int64
+ var relation, prov string
+ if err := rows.Scan(&from, &to, &relation, &prov); err != nil {
+ return nil, err
+ }
+ var w float64
+ switch relation {
+ case "wikilink":
+ if prov == "exact" {
+ w = 1.0
+ } else {
+ w = 0.5
+ }
+ case "entity":
+ w = 1.0
+ case "tag":
+ w = 0.5
+ default:
+ continue
+ }
+ add(from, to, w)
+ }
+ return adj, rows.Err()
+}
+```
+
+- [ ] **Step 5: 跑测试**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/graph/ ./internal/index/ 2>&1 | tail -5`
+Expected: PASS
+
+- [ ] **Step 6: CJK 混合检索（fts.go 加 KeywordSearch）**
+
+```go
+// containsCJK 是否含 CJK 统一表意文字
+func containsCJK(s string) bool {
+ for _, r := range s {
+ if r >= 0x4E00 && r <= 0x9FFF {
+ return true
+ }
+ }
+ return false
+}
+
+// KeywordSearch 双通道关键词检索：ASCII 词走 FTS5 MATCH，CJK 词走 LIKE（title/aliases/content/tags）。
+// FTS5 unicode61 把连续中文当整串单 token，多字符 CJK 词 MATCH 匹配不到，必须走 LIKE。
+func (s *Store) KeywordSearch(keywords []string, limit int) ([]FTSResult, error) {
+ if len(keywords) == 0 {
+ return nil, nil
+ }
+ seen := make(map[int64]*FTSResult)
+ var order []int64
+
+ // 通道 1: FTS（ASCII 词）
+ var ascii []string
+ for _, kw := range keywords {
+ if !containsCJK(kw) {
+ ascii = append(ascii, kw)
+ }
+ }
+ for _, kw := range ascii {
+ rows, err := s.db.Query(`
+ SELECT n.id, n.path, n.title, n.section, fts.rank
+ FROM nodes_fts fts JOIN nodes n ON n.id = fts.rowid
+ WHERE nodes_fts MATCH ? ORDER BY fts.rank LIMIT ?`, kw, limit)
+ if err != nil {
+ continue // 语法异常词跳过
+ }
+ for rows.Next() {
+ var r FTSResult
+ if err := rows.Scan(&r.ID, &r.Path, &r.Title, &r.Section, &r.Rank); err != nil {
+ continue
+ }
+ if _, ok := seen[r.ID]; !ok {
+ seen[r.ID] = &r
+ order = append(order, r.ID)
+ }
+ }
+ rows.Close()
+ }
+
+ // 通道 2: LIKE（CJK 词）
+ for _, kw := range keywords {
+ if !containsCJK(kw) {
+ continue
+ }
+ pat := "%" + kw + "%"
+ rows, err := s.db.Query(`
+ SELECT id, path, title, section FROM nodes
+ WHERE title LIKE ? OR aliases LIKE ? OR content_fts LIKE ? OR tags LIKE ?`,
+ pat, pat, pat, pat)
+ if err != nil {
+ continue
+ }
+ for rows.Next() {
+ var r FTSResult
+ if err := rows.Scan(&r.ID, &r.Path, &r.Title, &r.Section); err != nil {
+ continue
+ }
+ r.Rank = 0 // LIKE 无 rank
+ if _, ok := seen[r.ID]; !ok {
+ seen[r.ID] = &r
+ order = append(order, r.ID)
+ }
+ }
+ rows.Close()
+ }
+
+ results := make([]FTSResult, 0, len(order))
+ for _, id := range order {
+ results = append(results, *seen[id])
+ }
+ if limit > 0 && len(results) > limit {
+ results = results[:limit]
+ }
+ return results, nil
+}
+```
+
+- [ ] **Step 7: engine.go 双信号加权**
+
+替换 `Search` 主体（保留函数签名，`SearchOptions` 加 `TextWeight float64`，缺省 0.5）：
+
+```go
+func Search(store *index.Store, keywords []string, opts SearchOptions) ([]SearchResult, error) {
+ allKeywords := append(append(keywords, opts.Expanded...), opts.Symptom...)
+
+ // 1. 双通道检索
+ candidates, err := store.KeywordSearch(allKeywords, 100)
+ if err != nil {
+ return nil, err
+ }
+ if len(candidates) == 0 {
+ return nil, nil
+ }
+
+ // 2. 文本分（沿用位置加权，aliases 按 title 档计权）
+ textScore := make(map[int64]int, len(candidates))
+ for _, r := range candidates {
+ var score int
+ for _, kw := range keywords {
+ score += scoreResult(r, kw, ScoreNormal)
+ }
+ for _, kw := range opts.Expanded {
+ score += scoreResult(r, kw, ScoreExpanded)
+ }
+ for _, kw := range opts.Symptom {
+ score += scoreResult(r, kw, ScoreSymptom)
+ }
+ textScore[r.ID] = score
+ }
+
+ // 3. RWR 图质量（种子 = 全部候选，上限 20）
+ seedIDs := make([]int64, 0, len(candidates))
+ for _, r := range candidates {
+ if len(seedIDs) >= 20 {
+ break
+ }
+ seedIDs = append(seedIDs, r.ID)
+ }
+ rwrMass := map[int64]float64{}
+ if len(seedIDs) > 0 {
+ adj, err := store.LoadRWRGraph()
+ if err == nil {
+ rwrMass = graph.RWR(seedIDs, adj, 0.25)
+ }
+ }
+
+ // 4. 双信号加权：finalScore = norm(textScore)*tw + rwrMass*(1-tw)
+ tw := opts.TextWeight
+ if tw <= 0 || tw > 1 {
+ tw = 0.5
+ }
+ minT, maxT := 0, 0
+ for _, s := range textScore {
+ if s < minT || maxT == 0 && s > maxT {
+ minT = s
+ }
+ if s > maxT {
+ maxT = s
+ }
+ }
+ statusFactor := make(map[int64]float64)
+ for _, r := range candidates {
+ if r.Section == "待审阅" || isDraftStatus(r.Status) {
+ statusFactor[r.ID] = 0.6
+ } else {
+ statusFactor[r.ID] = 1.0
+ }
+ }
+
+ var results []SearchResult
+ for _, r := range candidates {
+ ts := float64(textScore[r.ID])
+ if maxT > minT {
+ ts = (ts - float64(minT)) / float64(maxT-minT)
+ } else if maxT > 0 {
+ ts = 1
+ }
+ final := ts*tw + rwrMass[r.ID]*(1-tw)
+ final *= statusFactor[r.ID]
+ results = append(results, SearchResult{
+ ID: r.ID, Path: r.Path, Title: r.Title, Section: r.Section,
+ Score: int(final * 100), Status: r.Status,
+ })
+ }
+ sort.Slice(results, func(i, j int) bool {
+ return results[i].Score > results[j].Score
+ })
+ if opts.TopN > 0 && len(results) > opts.TopN {
+ results = results[:opts.TopN]
+ }
+ // WithContent / WithLinks 逻辑沿用现有代码
+ if opts.WithContent {
+ for i := range results {
+ content, _, _, err := store.GetNodeContent(results[i].ID)
+ if err == nil {
+ results[i].Content = content
+ }
+ }
+ }
+ if opts.WithLinks {
+ for i := range results {
+ links, err := store.GetNodeLinks(results[i].ID)
+ if err == nil {
+ results[i].Links = links
+ }
+ }
+ }
+ return results, nil
+}
+
+// isDraftStatus 草稿态降权判断
+func isDraftStatus(status string) bool {
+ switch status {
+ case "草稿", "待确认", "跟进中":
+ return true
+ }
+ return false
+}
+```
+
+配套修改：
+- `FTSResult` 加 `Status string` 字段；`KeywordSearch` 两通道 SELECT 均加 `n.status` 列并 Scan
+- `SearchResult` 加 `Status string \`json:"status,omitempty"\``
+- `SearchOptions` 加 `TextWeight float64`
+- `scoreResult` 加 aliases 检查：`var aliasesJSON string` 从 store 取（或 FTSResult 带 Aliases []string 解析），命中按 "title" 档计权：
+
+```go
+// scoreResult 追加（Aliases 字段已在 FTSResult 上）：
+if len(r.Aliases) > 0 {
+ for _, a := range r.Aliases {
+ if strings.Contains(strings.ToLower(a), kw) {
+ score += CalcScore(keyword, "title", scoreType)
+ break
+ }
+ }
+}
+```
+（`FTSResult` 加 `Aliases []string`；KeywordSearch SELECT 加 `n.aliases` 并 json.Unmarshal）
+
+- `cmd/search.go`：`opts.TextWeight` 从 config 读（`cfg.Search.TextWeight`，缺省 0.5）
+- `internal/llm/client.go` Config 加：
+
+```go
+Search struct {
+ TextWeight float64 `yaml:"text_weight"`
+} `yaml:"search"`
+Explore struct {
+ DefaultBudget int `yaml:"default_budget"`
+ HardBudget int `yaml:"hard_budget"`
+ TopN int `yaml:"top_n"`
+} `yaml:"explore"`
+```
+
+- [ ] **Step 8: engine_test.go 适配 + 新测试**
+
+现有 `TestSearch` 保持通过（FTS 通道不变）。追加：
+
+```go
+func TestCJKLikeChannel(t *testing.T) {
+ // 库中含 "电子秤补气失败" 的文档，搜 "补气"（CJK）应命中
+ // 构造：store.UpsertNode 写入 content 含该词的节点
+ ...
+}
+```
+
+测试构造方式：`Open` 临时库 → `UpsertNode` 写 3 个节点（1 个 content 含"补气"，1 个 title 含"补气"，1 个不含）→ `Search(store, []string{"补气"}, opts)` → 断言含"补气"的两个在结果中且 title 命中者排前。
+
+- [ ] **Step 9: 全量测试**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"`
+Expected: 全 PASS
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add internal/graph/rwr.go internal/graph/rwr_test.go internal/index/graphload.go internal/index/fts.go internal/search/ internal/llm/client.go cmd/search.go
+git commit -m "feat: RWR 图结构排序 + CJK LIKE 混合检索 + 双信号加权 + aliases/status 参与排序"
+```
+
+---
+
+### Task 6: explore 命令
+
+**Files:**
+- Create: `cmd/explore.go`
+- Create: `internal/search/explore.go`
+- Create: `internal/search/explore_test.go`
+- Modify: `cmd/root.go`（注册 exploreCmd）
+
+**Interfaces:**
+- Consumes: Task 5 的 `Search`、`store.GetNodeContent`、`store.GetNodeLinks`
+- Produces:
+ - `func Explore(store *index.Store, query string, opts ExploreOptions) (*ExploreResult, error)`
+ - `type ExploreOptions struct { Budget, TopN int }`
+ - `type ExploreResult struct { Docs []ExploredDoc; Related map[string][]string; UnresolvedLinks []string }`
+ - `type ExploredDoc struct { Path, Title, Section string; Score int; Body string }`
+
+- [ ] **Step 1: 失败测试**
+
+`internal/search/explore_test.go`：
+
+```go
+package search
+
+import (
+ "testing"
+)
+
+// TestExploreParagraphExtraction 段落截取：只输出命中关键词的段落，整段不截半句
+func TestExploreParagraphExtraction(t *testing.T) {
+ content := "# 标题\n\n第一段讲称重。\n\n## 补气流程\n\n补气失败时先检查阀门。\n\n## 其他\n\n无关内容。\n"
+ got := extractRelevantParagraphs(content, []string{"补气"})
+ want := "## 补气流程\n\n补气失败时先检查阀门。\n"
+ if got != want {
+ t.Errorf("段落截取:\n got=%q\nwant=%q", got, want)
+ }
+}
+
+// TestExploreWholeDocWhenSmall 文档短于预算时整篇输出
+func TestExploreWholeDocWhenSmall(t *testing.T) {
+ got := extractRelevantParagraphs("短文档\n", []string{"不存在"}, 10000)
+ if got != "短文档\n" {
+ t.Errorf("应整篇输出: %q", got)
+ }
+}
+
+// TestExploreBudget 预算分配：按分数降序，超预算文档截断到段落边界
+func TestExploreBudget(t *testing.T) {
+ // 用 extractRelevantParagraphs 的预算版验证：预算 20 字节，命中段落 30 字节 → 输出空（宁缺毋滥，不截半段）
+ got := extractWithBudget("## 段落\n\n这是一段超过预算的内容啊\n", []string{"段落"}, 20)
+ if got != "" {
+ t.Errorf("超预算段落应跳过: %q", got)
+ }
+}
+```
+
+- [ ] **Step 2: 跑测试确认失败**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/search/ -run TestExplore -v`
+Expected: FAIL — `undefined: extractRelevantParagraphs`
+
+- [ ] **Step 3: 实现 explore.go**
+
+```go
+package search
+
+import (
+ "regexp"
+ "strings"
+
+ "github.com/aisim/kb-cli/internal/index"
+)
+
+var headingRe = regexp.MustCompile(`^#{1,4} .+$`)
+
+// splitParagraphs 按 1-4 级标题切段。无标题的文档整体为一段。
+func splitParagraphs(content string) []string {
+ lines := strings.Split(content, "\n")
+ var paras []string
+ var cur []string
+ flush := func() {
+ if len(cur) > 0 {
+ paras = append(paras, strings.TrimRight(strings.Join(cur, "\n"), "\n")+"\n")
+ cur = nil
+ }
+ }
+ for _, l := range lines {
+ if headingRe.MatchString(l) {
+ flush()
+ }
+ cur = append(cur, l)
+ }
+ flush()
+ return paras
+}
+
+// extractRelevantParagraphs 返回命中关键词的段落（整段不截半句）。
+// 文档总长 <= budget 时整篇输出；无命中段落时输出空串。
+func extractRelevantParagraphs(content string, keywords []string, budget int) string {
+ if budget <= 0 || len(content) <= budget {
+ return content
+ }
+ var out []string
+ for _, p := range splitParagraphs(content) {
+ for _, kw := range keywords {
+ if strings.Contains(p, kw) {
+ out = append(out, p)
+ break
+ }
+ }
+ }
+ // 预算约束：累计超预算的段落丢弃（不截半段）
+ var total int
+ kept := []string{}
+ for _, p := range out {
+ if total+len(p) > budget {
+ break
+ }
+ total += len(p)
+ kept = append(kept, p)
+ }
+ return strings.Join(kept, "")
+}
+
+// extractWithBudget extractRelevantParagraphs 的预算版（budget<=0 视为无预算）
+func extractWithBudget(content string, keywords []string, budget int) string {
+ if budget <= 0 {
+ budget = 100000
+ }
+ return extractRelevantParagraphs(content, keywords, budget)
+}
+
+// ExploreOptions explore 参数
+type ExploreOptions struct {
+ Budget int // 字节预算（0 = 用配置默认）
+ TopN int // 0 = 用配置默认
+}
+
+// ExploredDoc 入选文档及其输出正文
+type ExploredDoc struct {
+ Path string `json:"path"`
+ Title string `json:"title"`
+ Section string `json:"section"`
+ Score int `json:"score"`
+ Body string `json:"body"`
+}
+
+// ExploreResult explore 结果
+type ExploreResult struct {
+ Docs []ExploredDoc `json:"docs"`
+ Related map[string][]string `json:"related"`
+ UnresolvedLinks []string `json:"unresolved_links"`
+}
+
+// Explore 一次调用返回相关文档原文 + 关联清单 + 悬空链接
+func Explore(store *index.Store, query string, cfg ExploreOptions) (*ExploreResult, error) {
+ keywords := strings.Fields(query)
+ if len(keywords) == 0 {
+ return nil, nil
+ }
+ budget := cfg.Budget
+ if budget <= 0 {
+ budget = 16000
+ }
+ if budget > 32000 {
+ budget = 32000
+ }
+ topN := cfg.TopN
+ if topN <= 0 {
+ topN = 5
+ }
+
+ opts := SearchOptions{TopN: topN}
+ results, err := Search(store, keywords, opts)
+ if err != nil {
+ return nil, err
+ }
+ if len(results) == 0 {
+ return &ExploreResult{Related: map[string][]string{}}, nil
+ }
+
+ // 按分数降序分配预算：每文档至少 800 字节
+ res := &ExploreResult{Related: map[string][]string{}}
+ perDoc := budget / len(results)
+ if perDoc < 800 {
+ perDoc = 800
+ }
+ for i, r := range results {
+ content, _, _, err := store.GetNodeContent(r.ID)
+ if err != nil || content == "" {
+ continue
+ }
+ body := extractRelevantParagraphs(content, keywords, perDoc)
+ if body == "" {
+ // 无命中段落但文档入选 → 整篇（若放得下），否则跳过
+ if len(content) <= perDoc {
+ body = content
+ } else {
+ continue
+ }
+ }
+ res.Docs = append(res.Docs, ExploredDoc{
+ Path: r.Path, Title: r.Title, Section: r.Section,
+ Score: r.Score, Body: body,
+ })
+ // 关联清单
+ if links, err := store.GetNodeLinks(r.ID); err == nil {
+ res.Related[r.Path] = links
+ }
+ _ = i
+ }
+
+ // 悬空链接提示：入选文档的 wikilinks 中未解析的
+ for _, d := range res.Docs {
+ links, err := store.GetUnresolvedLinks(d.Path)
+ if err == nil {
+ res.UnresolvedLinks = append(res.UnresolvedLinks, links...)
+ }
+ }
+ return res, nil
+}
+```
+
+Store 需补方法（sqlite.go）：
+
+```go
+// GetUnresolvedLinks 某文档的悬空链接文本列表
+func (s *Store) GetUnresolvedLinks(path string) ([]string, error) {
+ rows, err := s.db.Query(`
+ SELECT u.link_text FROM unresolved_links u
+ JOIN nodes n ON n.id = u.from_node WHERE n.path = ?`)
+ if err != nil {
+ return nil, err
+ }
+ defer rows.Close()
+ var links []string
+ for rows.Next() {
+ var l string
+ rows.Scan(&l)
+ links = append(links, l)
+ }
+ return links, rows.Err()
+}
+```
+
+- [ ] **Step 4: cmd/explore.go**
+
+```go
+package cmd
+
+import (
+ "fmt"
+ "os"
+
+ "github.com/aisim/kb-cli/internal/index"
+ "github.com/aisim/kb-cli/internal/search"
+ "github.com/spf13/cobra"
+)
+
+var (
+ exploreBudget int
+ exploreTopN int
+ exploreJSON bool
+)
+
+var exploreCmd = &cobra.Command{
+ Use: "explore <问题>",
+ Short: "一次调用获取相关文档原文 + 关联清单（供 agent 使用）",
+ Long: `# explore - 精准上下文
+kb-cli explore <问题> [--budget 字节] [--top N] [--json] # 按字节预算返回相关文档原文、关联文档、悬空链接`,
+ Args: cobra.MinimumNArgs(1),
+ RunE: runExplore,
+}
+
+func init() {
+ rootCmd.AddCommand(exploreCmd)
+ exploreCmd.Flags().IntVar(&exploreBudget, "budget", 0, "字节预算（0=配置默认 16000）")
+ exploreCmd.Flags().IntVar(&exploreTopN, "top", 0, "文档数（0=配置默认 5）")
+ exploreCmd.Flags().BoolVar(&exploreJSON, "json", false, "JSON 输出")
+ exploreCmd.SetUsageTemplate(exploreCmd.Long)
+}
+
+func runExplore(cmd *cobra.Command, args []string) error {
+ store, err := index.Open(dbPath)
+ if err != nil {
+ return fmt.Errorf("打开索引失败: %w", err)
+ }
+ defer store.Close()
+
+ dirty, err := index.QuickCheck(store, vaultPath)
+ if err != nil {
+ return fmt.Errorf("索引状态检查失败: %w", err)
+ }
+ if dirty {
+ fmt.Fprintln(os.Stderr, "索引有变更，正在增量同步...")
+ if err := syncIndex(store); err != nil {
+ return fmt.Errorf("增量同步失败: %w", err)
+ }
+ }
+
+ query := strings.Join(args, " ")
+ res, err := search.Explore(store, query, search.ExploreOptions{Budget: exploreBudget, TopN: exploreTopN})
+ if err != nil {
+ return fmt.Errorf("explore 失败: %w", err)
+ }
+ if len(res.Docs) == 0 {
+ fmt.Println("未找到相关文档")
+ return nil
+ }
+
+ if exploreJSON {
+ b, _ := json.MarshalIndent(res, "", " ")
+ fmt.Println(string(b))
+ return nil
+ }
+ for _, d := range res.Docs {
+ fmt.Printf("## %s（%s，score %d）\n", d.Title, d.Path, d.Score)
+ fmt.Print(d.Body)
+ fmt.Println()
+ if rel, ok := res.Related[d.Path]; ok && len(rel) > 0 {
+ fmt.Printf("关联: %s\n", strings.Join(rel, ", "))
+ }
+ fmt.Println()
+ }
+ if len(res.UnresolvedLinks) > 0 {
+ fmt.Printf("⚠️ 悬空链接: %s\n", strings.Join(res.UnresolvedLinks, ", "))
+ }
+ fmt.Println("以上为文档原文直出，agent 无需再读文件")
+ return nil
+}
+```
+
+import 需加 `encoding/json` 和 `strings`。
+
+- [ ] **Step 5: 跑测试 + 编译**
+
+Run: `CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files" && CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go build -o kb-cli .`
+Expected: 全 PASS + 二进制产出
+
+- [ ] **Step 6: 手动冒烟**
+
+```bash
+CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go build -o kb-cli .
+./kb-cli index build --vault ~/rag-lpg-obsidian
+./kb-cli explore "电子秤补气失败" --top 3
+```
+Expected: 输出含补气相关文档原文段落 + 关联清单 + "原文直出"尾注
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add cmd/explore.go internal/search/explore.go internal/search/explore_test.go internal/index/sqlite.go
+git commit -m "feat: explore 命令（字节预算 + 段落级原文直出 + 关联清单 + 悬空链接提示）"
+```
+
+---
+
+### Task 7: 端到端验证 + README
+
+**Files:**
+- Modify: `README.md`（命令文档更新）
+- Create: `scripts/e2e-verify.sh`
+
+**Interfaces:**
+- Consumes: Task 1-6 全部产物
+
+- [ ] **Step 1: e2e 验证脚本**
+
+`scripts/e2e-verify.sh`：
+
+```bash
+#!/bin/bash
+# 端到端验证（对标 spec 测试计划第 2 节）
+set -e
+export CGO_CFLAGS="-DSQLITE_ENABLE_FTS5"
+export CGO_LDFLAGS="-lm"
+VAULT="${1:-$HOME/rag-lpg-obsidian}"
+cd "$(dirname "$0")/.."
+go build -o /tmp/kb-cli-e2e .
+
+echo "=== 1. 全量重建基准 ==="
+/tmp/kb-cli-e2e index build --vault "$VAULT" --force 2>&1 | tail -1
+
+echo "=== 2. 增量同步耗时 ==="
+time /tmp/kb-cli-e2e index build --vault "$VAULT" 2>&1 | tail -1
+
+echo "=== 3. 未 commit 编辑可见性 ==="
+TESTFILE="$VAULT/笔记/e2e-test-$(date +%s).md"
+printf -- "---\ntitle: e2e测试\ntags: [补气]\n---\ne2e 补气测试内容\n" > "$TESTFILE"
+/tmp/kb-cli-e2e search e2e --vault "$VAULT" --top 3 2>&1 | grep -q "e2e测试" && echo "PASS: 未commit编辑可见" || echo "FAIL: 未commit编辑不可见"
+rm -f "$TESTFILE"
+/tmp/kb-cli-e2e index build --vault "$VAULT" 2>/dev/null
+
+echo "=== 4. CJK 召回质量（补气应命中多条）==="
+N=$(/tmp/kb-cli-e2e search 补气 --vault "$VAULT" --top 10 2>/dev/null | grep -c "^文档/\|^FAQ/\|^知识/" || true)
+echo "补气 命中 $N 条 (期望 >= 5)"
+
+echo "=== 5. explore 预算内 ==="
+BYTES=$(/tmp/kb-cli-e2e explore "电子秤补气失败" --vault "$VAULT" --top 3 2>/dev/null | wc -c)
+echo "explore 输出 ${BYTES} 字节 (上限 32000+尾注)"
+
+echo "=== 6. 悬空补全 ==="
+/tmp/kb-cli-e2e graph stats --vault "$VAULT" 2>&1 | head -5
+```
+
+- [ ] **Step 2: 跑 e2e**
+
+Run: `bash scripts/e2e-verify.sh`
+Expected: 第 3 项 PASS；第 4 项 N>=5（改造前实测为 1）；第 5 项 BYTES <= 32200
+
+- [ ] **Step 3: README 更新**
+
+README.md 命令章节更新：
+- `index build` 说明改"默认增量对账同步，`--force` 全量重建"
+- `search` 说明加"ASCII 走 FTS5、CJK 走 LIKE 双通道；排序 = 文本分 + RWR 图质量双信号"
+- 新增 `explore` 命令说明
+- 新增"构建要求"章节：`CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go build`（或 make build）
+- `graph query/related` 输出含 provenance 标注说明
+
+- [ ] **Step 4: 最终全量测试 + 提交推送**
+
+```bash
+CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"
+git add README.md scripts/e2e-verify.sh
+git commit -m "docs: e2e 验证脚本 + README 更新（增量同步/explore/构建要求）"
+git push
+```
+
+---
+
+## Self-Review
+
+**Spec 覆盖检查：**
+- §1.1 RWR → Task 5 Step 1-5 ✅
+- §1.2 aliases 进 FTS → Task 1（FTS 表加列）+ Task 5 Step 6-7 ✅
+- §1.3 status 降权 → Task 5 Step 7 ✅
+- §2.1 provenance → Task 3 ✅
+- §2.2 悬空补全 → Task 3（入表）+ Task 4（重试）✅
+- §3.1 对账 → Task 2 ✅
+- §3.2 FTS external-content → Task 1 Step 6 ✅
+- §3.3 schema 迁移 + 备份 → Task 1 Step 4 ✅
+- §4 explore → Task 6 ✅
+- §5 config → Task 5 Step 7（Config 加节）+ Task 6（读 config 缺省值）✅
+- 测试计划 5 项 → Task 1-6 各单测 + Task 7 e2e ✅
+
+**额外修复（spec 外，实测发现的既有 bug）：** CJK 词 FTS5 MATCH 失效 → Task 5 的 LIKE 通道。此为搜索质量层的必要组成部分，已在 spec 的"搜索质量提升"目标内。
+
+**类型一致性：** `graph.Edge.Provenance`（Task 3 定义，Task 4/5 使用）；`index.FileStat`（Task 2 定义）；`search.ExploreOptions`（Task 6 定义）；`vault.FileMeta.Status/Aliases`（Task 2 定义，Task 3 的 graph.Node 对齐）。`RetryUnresolved` 签名 Task 2 占位 `() {}` → Task 4 改 `(int, error)`——Task 2 的 reconcile 调用处写 `store.RetryUnresolved()` 不接收返回值，兼容两种签名。✅
+
+**Placeholder 扫描：** 无 TBD/TODO；所有代码步骤含完整代码。Task 2 Step 5 的 `resolveWikilink` 与 Task 3 的 `matchWikilink` 是两套实现（DB 版/内存版），规则一致，注释已说明。✅
--
Gitblit v1.10.0