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
CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm"——本机 gcc 下 go-sqlite3 自带 amalgamation 链接 libm 失败导致 FTS5 编译失败；系统 libsqlite3 (3.45.1) 原生含 FTS5，加此两参数后全部测试通过。已存于 go.env，Makefile 必须固化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)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
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）带增删改触发器
# 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
internal/index/migrations_test.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"。
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -run TestMigrate -v
Expected: FAIL — store.migrate undefined
internal/index/migrations.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
}
internal/index/sqlite.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，幂等）。
internal/index/fts.go 替换 CreateFTS/PopulateFTS：
// 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
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"
Expected: 全部 PASS（含迁移测试 3 个 + 既有 FTS/search 测试）
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 构建标志"
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 }
internal/vault/parser.go Frontmatter 加字段 + ParseFile 赋值：
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）：
// 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
}
internal/index/reconcile_test.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")
}
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -run TestReconcile -v
Expected: FAIL — undefined: Reconcile
// 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 对齐）。
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 列。
reconcile.go 底部：
// RetryUnresolved 重试解析悬空链接（Task 4 补全完整实现）
func (s *Store) RetryUnresolved() {}
cmd/rebuild.go：rebuildIndex 保留为全量路径（改名 rebuildFull），新增：
// 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 改为：
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）。
// 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
}
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 + 编译通过
git add internal/index/ internal/vault/ internal/graph/model.go cmd/
git commit -m "feat: 增量对账同步（stat+sha256 比对，替代 commit hash 全量重建）"
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
internal/graph/builder_test.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)
}
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/graph/ -run TestBuildGraphProvenance -v
Expected: FAIL — Provenance 未定义 / BuildGraph 返回值不匹配
internal/graph/model.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 匹配循环中：
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 升级：
// 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 改：
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：
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）。
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"
Expected: 全 PASS
git add internal/graph/ internal/index/sqlite.go cmd/rebuild.go
git commit -m "feat: wikilink 边可信度标注（exact/fuzzy）+ 悬空链接入 unresolved_links 表"
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)——每次对账后调用
internal/index/unresolved_test.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)
}
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -run TestRetryUnresolved -v
Expected: FAIL — RetryUnresolved 是空实现，悬空行不清除
reconcile.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（已有）。
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/index/ -v 2>&1 | tail -20
Expected: 全 PASS（含 Task 2 的 5 个对账测试）
git add internal/index/
git commit -m "feat: 悬空双链自动补全（新文档入库后历史链接自动解析建边）"
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
internal/graph/rwr_test.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])
}
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/graph/ -run TestRWR -v
Expected: FAIL — undefined: RWR
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
}
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()
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/graph/ ./internal/index/ 2>&1 | tail -5
Expected: PASS
// 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
}
替换 Search 主体（保留函数签名，SearchOptions 加 TextWeight float64，缺省 0.5）：
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" 档计权：
// 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 加：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"`
现有 TestSearch 保持通过（FTS 通道不变）。追加：
func TestCJKLikeChannel(t *testing.T) {
// 库中含 "电子秤补气失败" 的文档，搜 "补气"（CJK）应命中
// 构造：store.UpsertNode 写入 content 含该词的节点
...
}
测试构造方式：Open 临时库 → UpsertNode 写 3 个节点（1 个 content 含"补气"，1 个 title 含"补气"，1 个不含）→ Search(store, []string{"补气"}, opts) → 断言含"补气"的两个在结果中且 title 命中者排前。
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./... 2>&1 | grep -v "no test files"
Expected: 全 PASS
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 参与排序"
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 }
internal/search/explore_test.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)
}
}
Run: CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" CGO_LDFLAGS="-lm" go test ./internal/search/ -run TestExplore -v
Expected: FAIL — undefined: extractRelevantParagraphs
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）：
// 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()
}
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。
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 + 二进制产出
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: 输出含补气相关文档原文段落 + 关联清单 + "原文直出"尾注
git add cmd/explore.go internal/search/explore.go internal/search/explore_test.go internal/index/sqlite.go
git commit -m "feat: explore 命令（字节预算 + 段落级原文直出 + 关联清单 + 悬空链接提示）"
Files:
- Modify: README.md（命令文档更新）
- Create: scripts/e2e-verify.sh
Interfaces:
- Consumes: Task 1-6 全部产物
scripts/e2e-verify.sh：
#!/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
Run: bash scripts/e2e-verify.sh
Expected: 第 3 项 PASS；第 4 项 N>=5（改造前实测为 1）；第 5 项 BYTES <= 32200
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 标注说明
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
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 版/内存版），规则一致，注释已说明。✅