docs: e2e 验证脚本 + README 更新（增量同步/explore/构建要求）

ax_rd

4 hours ago 60eb89c12ee0661785395bff90940204b16dcb3a

 cmd/index.go

@@ -17,62 +17,28 @@
   Short: "索引管理",
}

// forceRebuild index build 的 --force flag：全量重建索引
var forceRebuild bool

var indexBuildCmd = &cobra.Command{
   Use:   "build",
   Short: "构建或重建知识库索引",
   Long: `# index build - 构建或重建知识库索引
kb-cli index build [--vault=<路径>]

操作说明：
  1. 扫描知识库目录下的所有 Markdown 文件
  2. 解析 frontmatter、标签、实体、wikilinks
  3. 构建知识图谱并写入 SQLite 数据库
  4. 创建 FTS5 全文索引

参数：
  --vault <路径>    知识库根目录（默认：~/aisim/note/001/笔记001）
  --db <路径>       索引数据库路径（默认：~/.cache/kb-cli/kb.db）`,
   RunE: runIndexBuild,
   Long:  `kb-cli index build [--vault <路径>] [--db <路径>] [--force] # 构建或重建知识库索引（默认增量对账，--force 全量重建）`,
   RunE:  runIndexBuild,
}

var indexStatusCmd = &cobra.Command{
   Use:   "status",
   Short: "查看索引状态信息",
   Long: `# index status - 查看索引状态信息
kb-cli index status

输出信息：
  - 知识库路径
  - 索引文件路径
  - 节点数量
  - 边数量
  - 索引 commit
  - 当前 commit
  - 构建时间
  - 是否需要更新

参数：
  --vault <路径>    知识库根目录（默认：~/aisim/note/001/笔记001）
  --db <路径>       索引数据库路径（默认：~/.cache/kb-cli/kb.db）`,
   RunE: runIndexStatus,
   Long:  `kb-cli index status [--vault <路径>] [--db <路径>] # 查看索引状态（节点数、边数、commit、构建时间）`,
   RunE:  runIndexStatus,
}

var indexGcCmd = &cobra.Command{
   Use:   "gc",
   Short: "清理孤立节点和边",
   Long: `# index gc - 清理孤立节点和边
kb-cli index gc

操作说明：
  1. 扫描索引中的所有节点
  2. 检查对应的 Markdown 文件是否存在
  3. 删除不存在的文件对应的节点和边
  4. 输出清理的节点数量

参数：
  --vault <路径>    知识库根目录（默认：~/aisim/note/001/笔记001）
  --db <路径>       索引数据库路径（默认：~/.cache/kb-cli/kb.db）`,
   RunE: runIndexGc,
   Long:  `kb-cli index gc [--vault <路径>] [--db <路径>] # 清理索引中文件已删除的孤立节点和边`,
   RunE:  runIndexGc,
}

var gitCmd = &cobra.Command{
@@ -83,18 +49,8 @@
var gitSyncCmd = &cobra.Command{
   Use:   "sync",
   Short: "同步知识库到 Git 仓库",
   Long: `# git sync - 同步知识库到 Git 仓库
kb-cli git sync

操作说明：
  1. 检查知识库目录是否是 Git 仓库
  2. 执行 git add -A 添加所有变更
  3. 如果有变更，执行 git commit（自动生成提交信息）
  4. 执行 git push 推送到远程仓库

参数：
  --vault <路径>    知识库根目录（默认：~/aisim/note/001/笔记001）`,
   RunE: runGitSync,
   Long:  `kb-cli git sync [--vault <路径>] # 执行 git add、commit、push 同步知识库`,
   RunE:  runGitSync,
}

func init() {
@@ -102,6 +58,7 @@
   indexCmd.AddCommand(indexBuildCmd)
   indexCmd.AddCommand(indexStatusCmd)
   indexCmd.AddCommand(indexGcCmd)
   indexBuildCmd.Flags().BoolVar(&forceRebuild, "force", false, "全量重建索引（默认走增量对账）")
   
   rootCmd.AddCommand(gitCmd)
   gitCmd.AddCommand(gitSyncCmd)
@@ -115,19 +72,26 @@
   }
   defer store.Close()

   // 获取当前 commit
   commit, err := index.GetGitCommit(vaultPath)
   if err != nil {
      fmt.Fprintln(os.Stderr, "警告: 无法获取 git commit:", err)
      commit = ""
   if forceRebuild {
      // 全量重建
      commit, err := index.GetGitCommit(vaultPath)
      if err != nil {
         fmt.Fprintln(os.Stderr, "警告: 无法获取 git commit:", err)
         commit = ""
      }
      fmt.Fprintln(os.Stderr, "正在全量重建索引...")
      if err := rebuildFull(store, commit); err != nil {
         return fmt.Errorf("重建索引失败: %w", err)
      }
      fmt.Fprintln(os.Stderr, "索引重建完成")
      return nil
   }

   fmt.Fprintln(os.Stderr, "正在重建索引...")
   if err := rebuildIndex(store, commit); err != nil {
      return fmt.Errorf("重建索引失败: %w", err)
   // 默认走增量对账
   if err := syncIndex(store); err != nil {
      return fmt.Errorf("增量同步失败: %w", err)
   }

   fmt.Fprintln(os.Stderr, "索引重建完成")
   fmt.Fprintln(os.Stderr, "索引同步完成")
   return nil
}

@@ -174,14 +138,14 @@
   fmt.Printf("  当前 commit: %s\n", currentCommit)
   fmt.Printf("  构建时间: %s\n", builtAt)

   // 检查是否需要更新
   needsRebuild, _, err := index.NeedsRebuild(store, vaultPath)
   // 检查是否有变更（stat 快速比对）
   dirty, err := index.QuickCheck(store, vaultPath)
   if err != nil {
      return fmt.Errorf("检查索引状态失败: %w", err)
   }

   if needsRebuild {
      fmt.Printf("  状态: 需要更新\n")
   if dirty {
      fmt.Printf("  状态: 有变更\n")
   } else {
      fmt.Printf("  状态: 最新\n")
   }