# CLI 命令参考

## 全局选项

```bash
index1 [--version] [-v|--verbose] <command>
```

| 选项 | 说明 |
|------|------|
| `--version` | 显示版本号 |
| `-v, --verbose` | 详细输出（DEBUG 级别日志） |

---

## index — 索引文件

```bash
index1 index <paths...> [-c COLLECTION] [--force] [--resume]
```

扫描文件/目录，执行分块、embedding、符号提取、入库。

| 参数/选项 | 说明 |
|-----------|------|
| `paths` | 要索引的文件或目录（可多个） |
| `-c, --collection` | 集合名称（命名空间隔离） |
| `--force` | 强制全量重索引（忽略文件 hash 缓存） |
| `--resume` | 续传上次中断的索引任务 |

```bash
index1 index ./src ./docs                # 索引两个目录
index1 index ./src -c my_project         # 指定集合
index1 index --force ./src               # 强制重建
index1 index --resume                    # 续传失败文件
```

---

## backfill — 回填向量

```bash
index1 backfill [-c COLLECTION]
```

不重新分块，只为缺失 embedding 的 chunk 补充向量。适用于切换 embedding 后端后。

---

## search — 搜索

```bash
index1 search <query> [-c COLLECTION] [-k TOP_K] [--verbose]
```

BM25 + 向量混合搜索。

| 参数/选项 | 说明 |
|-----------|------|
| `query` | 搜索查询文本 |
| `-c, --collection` | 限定搜索范围 |
| `-k, --top-k` | 返回结果数量（默认 5） |
| `--verbose` | 显示完整内容 |

```bash
index1 search "认证流程"
index1 search "auth API" -c proj_a -k 10
index1 search "数据库连接" --verbose
```

---

## status — 查看状态

```bash
index1 status
```

显示索引统计：数据库路径、文档数、片段数、集合列表、向量搜索可用性、最近索引记录。

---

## config — 配置管理

```bash
index1 config [key] [value] [--backend BACKEND]
```

查看或修改配置。

| 用法 | 说明 |
|------|------|
| `index1 config` | 显示全部配置 |
| `index1 config embedding_model` | 查看单个配置项 |
| `index1 config top_k 20` | 修改配置项 |
| `index1 config --backend ollama` | 快捷切换后端预设 |

---

## init — 初始化配置

```bash
index1 init [--backend BACKEND]
```

交互式选择 embedding 后端和模型。

| 选项 | 说明 |
|------|------|
| `--backend` | 快捷选择：`ollama` / `llama-cpp` / `lm-studio` / `custom` |

```bash
index1 init                      # 交互式
index1 init --backend ollama     # 直接切换到 Ollama
index1 init --backend lm-studio  # 切换到 LM Studio
```

---

## repo-map — 代码结构地图

```bash
index1 repo-map [-c COLLECTION] [--budget TOKENS] [--focus FILE...]
```

生成 Aider 风格的项目代码结构地图（需要 codegraph 依赖）。

| 选项 | 说明 |
|------|------|
| `-c, --collection` | 集合名称 |
| `--budget` | Token 预算（默认 1024） |
| `--focus` | 聚焦文件路径（可多个） |

```bash
index1 repo-map
index1 repo-map --focus src/search.py --budget 2048
```

---

## symbols — 符号查看

```bash
index1 symbols [FILE_PATH] [-c COLLECTION] [--rank]
```

查看文件符号列表或全局符号统计。

| 用法 | 说明 |
|------|------|
| `index1 symbols src/main.py` | 查看文件的函数/类/方法 |
| `index1 symbols` | 全局符号统计 |
| `index1 symbols --rank` | 按 PageRank 排序 top 20 |

---

## web — Web UI

```bash
index1 web [-p PORT] [--host HOST]
```

启动 Web UI（默认 http://127.0.0.1:6888）。

---

## watch — 文件监听

```bash
index1 watch <paths...> [-c COLLECTION]
```

监听文件变更，自动重索引。`Ctrl+C` 停止。

```bash
index1 watch ./src ./docs -c my_project
```

---

## doctor — 环境检查

```bash
index1 doctor [--fix]
```

检查 embedding 后端配置、连接状态。`--fix` 自动修复发现的问题。

---

## serve — MCP Server

```bash
index1 serve
```

启动 MCP Server（stdio 模式），供 Claude Code 等 AI 工具调用。

---

## cog — 认知记忆管理

认知记忆子命令组。

### cog status — 认知统计

```bash
index1 cog status
```

显示认知数据库统计：事实总数、活跃事实、心智模型、向量搜索状态。

### cog recall — 搜索认知记忆

```bash
index1 cog recall <query> [-c COLLECTION] [-k TOP_K]
```

```bash
index1 cog recall "FTS5 问题"
index1 cog recall "部署配置" -c my_project
```

### cog list — 列出事实

```bash
index1 cog list [-c COLLECTION] [-n LIMIT]
```

列出最近的认知事实（默认 10 条）。

### cog doctor — 诊断

```bash
index1 cog doctor [-c COLLECTION]
```

诊断认知数据库：量化字段填充率，发现数据质量问题。

### cog rebuild — 从 Git 重建

```bash
index1 cog rebuild [-c COLLECTION] [--since DATE] [-n LIMIT] [--dry-run] [--repo PATH]
```

从 git history 重建认知事实。

| 选项 | 说明 |
|------|------|
| `-c, --collection` | 集合名称（默认从当前目录推断） |
| `--since` | 起始日期（如 `2025-01-01` 或 `3 months ago`） |
| `-n, --limit` | 最大 commit 数（默认 500） |
| `--dry-run` | 仅统计，不写入 |
| `--repo` | Git 仓库路径（默认当前目录） |

```bash
index1 cog rebuild --dry-run           # 预览
index1 cog rebuild --since "3 months ago"
index1 cog rebuild -c my_project -n 200
```

---

## hook — Hook 事件处理

```bash
index1 hook <EVENT>
```

处理 Claude Code Hook 事件（一般由 Claude Code 自动调用，无需手动执行）。

支持的事件：`SessionStart`、`UserPromptSubmit`、`PostToolUse`、`SessionEnd`
