@mars167/git-ai 2.3.0

package/docs/zh-CN/architecture_explained.md

@@ -0,0 +1,116 @@
+# 技术架构与选型深度解析
+
+本文档旨在从架构设计角度，深入剖析 `git-ai` 的核心实现原理、关键技术选型及其背后的决策逻辑。适用于技术评审、架构选型参考及二次开发指导。
+
+## 1. 核心架构设计理念
+
+`git-ai` 的设计目标是构建一个**轻量级、去中心化、零依赖**的代码库语义索引引擎。不同于传统的集中式代码搜索服务（如 Sourcegraph），`git-ai` 采用“Client-Side Indexing”模式，将索引能力下沉至开发者本地环境。
+
+### 1.1 设计哲学：Hybrid RAG 与 高召回策略
+
+我们采用了 **Hybrid RAG (混合检索增强生成)** 的设计思想，通过不同组件的协同来平衡检索的精度与召回率。核心原则是 **"Recall over Precision"（召回优于精度）** —— 宁可多搜几个交给 AI (LLM) 去过滤，也绝不漏掉潜在的关键信息。
+
+*   **Tree-sitter (骨架提取)**：负责“精准”的结构化数据。提取代码的类、方法、接口定义，构建代码的“骨架”。
+*   **CozoDB (关联推导)**：负责“逻辑”连接。处理继承、实现、包含等图关系，支持多跳查询（如“查找所有子类”）。
+*   **LanceDB (语义仲裁)**：负责“模糊”召回。通过 Hash Embedding 捕捉代码的语义特征，即使不知道确切名字，也能通过上下文找到相关代码。
+*   **AI (最终过滤)**：作为 RAG 的最后一环，LLM 利用其强大的理解能力，对召回的混合结果进行 Re-ranking 和精确过滤。
+
+**核心约束：**
+*   **零环境依赖**：不依赖 Docker、JVM、Python 环境，开箱即用。
+*   **纯本地运行**：数据隐私优先，无需上传代码至云端。
+*   **高性能**：毫秒级检索，索引体积可控（通常 < 代码体积的 20%）。
+
+---
+
+## 2. 索引流水线 (Indexing Pipeline)
+
+索引构建过程是一个典型的 ETL (Extract, Transform, Load) 流程，分为三个阶段：
+
+### 2.1 结构化解析 (Parsing & Chunking)
+
+为了解决传统基于行的分片（Line-based Chunking）导致的语义截断问题，我们采用了基于 AST（抽象语法树）的结构化分片策略。
+
+*   **技术选型：Tree-sitter**
+    *   **背景**：GitHub Atom 团队开发的增量解析系统，现已成为代码解析领域的工业标准。
+    *   **实现机制**：通过 `tree-sitter-{lang}` 生成具体语言的 CST (Concrete Syntax Tree)，再通过遍历算法提取 Symbol（类、函数、接口）及其上下文（Range）。
+    *   **优势**：
+        *   **多语言支持**：通过统一的 WASM/Node.js 绑定支持几十种主流语言。
+        *   **容错性**：即使代码存在语法错误，仍能构建部分 AST，保证索引鲁棒性。
+        *   **性能**：基于 C 编写，解析速度极快（单文件 < 10ms）。
+
+### 2.2 向量化 (Embedding)
+
+这是将非结构化代码转换为结构化向量的关键步骤。
+
+*   **技术选型：Random Indexing (Deterministic Hash Embedding)**
+    *   **背景**：一种降维技术，基于 Johnson-Lindenstrauss 引理（高维空间中的随机向量近似正交）。
+    *   **实现机制**：
+        1.  **Tokenization**：对代码标识符进行分词与归一化。
+        2.  **Hashing**：计算 Token 的 SHA-256 哈希。
+        3.  **Projection**：将哈希映射到固定维度（如 256 维）的稀疏向量中（+1/-1）。
+        4.  **Aggregation**：叠加所有 Token 向量并归一化。
+    *   **决策依据（VS 深度学习模型）**：
+        *   **Transformer 模型 (如 BERT/OpenAI)**：虽然语义理解强，但模型文件巨大（数百 MB）、推理延迟高、且通常需要 GPU 或云端 API，违背了“轻量级 CLI”的设计初衷。
+        *   **Hash Embedding**：虽然无法捕捉同义词语义（如 Login ≈ SignIn），但在代码搜索场景中，**精确的标识符匹配**（Identifier Match）往往比模糊语义更重要。该方案实现了**零模型文件依赖、纳秒级推理速度**。
+
+### 2.3 关系图谱构建 (Knowledge Graph)
+
+为了弥补向量检索在结构化查询（如继承关系、嵌套结构）上的不足，我们同步构建了 AST 关系图。
+
+*   **模型设计**：
+    *   **节点**：File, Symbol (Class, Method, Interface)
+    *   **边**：Contains (包含), Extends (继承), Implements (实现)
+    *   *注：当前版本主要关注“定义（Definition）”关系，暂未包含“引用（Reference/Call Graph）”关系，以保持索引构建的轻量化。*
+*   **存储**：将 AST 关系降维为 Datalog 事实表（Facts），存入图数据库。
+
+---
+
+## 3. 存储引擎选型 (Storage Engine)
+
+我们采用了“双引擎”策略，分别处理向量检索和图查询。
+
+### 3.1 向量存储：LanceDB
+
+*   **技术背景**：基于 Apache Arrow 和 Lance 数据格式的新一代向量数据库。
+*   **选型理由**：
+    *   **Serverless 架构**：不同于 Milvus/Qdrant 需要独立服务进程，LanceDB 是嵌入式的（类似 SQLite），数据即文件。
+    *   **列式存储**：原生支持 Arrow 格式，Zero-copy 读取，极大降低内存开销。
+    *   **多模态支持**：单表支持向量索引（IVF-PQ）与标量字段（全文检索），便于混合查询。
+    *   **Rust 内核**：保证了极高的 I/O 吞吐和稳定性。
+
+### 3.2 图存储：CozoDB
+
+*   **技术背景**：基于 Datalog 的事务型、关系型/图混合数据库。
+*   **选型理由**：
+    *   **递归查询能力**：原生支持 Datalog 推理规则，能够优雅处理代码中的递归结构（如多层继承链、模块依赖树），这是标准 SQL (SQLite) 难以高效实现的。
+    *   **轻量级嵌入**：底层存储引擎可插拔（支持 RocksDB, SQLite, Sled），我们默认使用 SQLite 后端，保持了单文件部署的简洁性。
+    *   **WASM 支持**：具备回退到纯内存 WASM 模式的能力，保证在极端环境下的可用性。
+
+---
+
+## 4. 技术栈横向对比 (Benchmark & Comparison)
+
+| 维度 | git-ai (本方案) | Sourcegraph (Zoekt) | CTags / GTags | 基于 OpenAI 的方案 |
+| :--- | :--- | :--- | :--- | :--- |
+| **核心算法** | Hash Embedding + AST Graph | Trigram Index (N-gram) | 正则/词法分析 | LLM Embedding |
+| **检索模式** | 混合检索 (语义+结构) | 精确/正则匹配 | 符号跳转 | 纯语义相似度 |
+| **依赖环境** | Node.js Runtime (零外部依赖) | Go Server, Docker | C 编译环境 | Python/GPU/API Key |
+| **索引体积** | 小 (~15-20%) | 中等 (~30%) | 极小 (<5%) | 极大 (向量维度高) |
+| **语义理解** | 中 (基于词袋模型) | 无 | 无 | 高 |
+| **部署成本** | **极低 (CLI 工具)** | 高 (需运维集群) | 低 | 中/高 |
+
+## 5. 总结与展望
+
+`git-ai` 的架构本质上是在**检索效果**与**工程成本**之间寻找的一个极致平衡点。
+
+通过 **Tree-sitter + Hash Embedding + LanceDB + CozoDB** 的组合，我们在不引入任何重型依赖的前提下，实现了对代码库的**语义级（Vector）**和**结构级（Graph）**的双重索引。这种架构特别适合作为 AI Agent 的“代码知识外脑”，为其提供精准、快速的上下文检索能力。
+
+## 6. 按提交语义工件（DSR）
+
+除了面向当前 checkout 的 `.git-ai/` 索引缓存外，`git-ai` 还提供 DSR（Deterministic Semantic Record）作为 **按提交（per-commit）** 的语义工件：
+
+- 每个 commit 对应一份 DSR 文件：`.git-ai/dsr/<commit_hash>.json`
+- DSR 必须不可变且确定性；数据库索引仅作可删缓存（可由 DSR + Git 重建）
+- 历史遍历必须从 Git DAG 出发，DSR 只 enrich 节点，不定义边
+
+详见：[DSR 文档](./dsr.md)

package/docs/zh-CN/cli.md

@@ -0,0 +1,109 @@
+# 命令行使用
+
+## git 代理模式
+
+```bash
+git-ai init
+git-ai status
+git-ai add -A
+git-ai commit -m "msg"
+git-ai push -u origin main
+```
+
+## AI 子命令
+
+```bash
+git-ai ai status
+git-ai ai index --overwrite
+git-ai ai index --incremental --staged
+git-ai ai query "search text" --limit 20
+git-ai ai query "get*repo" --mode wildcard --case-insensitive --limit 20
+git-ai ai semantic "semantic query" --topk 10
+git-ai ai graph find "Foo"
+git-ai ai graph children src/mcp/server.ts --as-file
+git-ai ai graph query "?[name, kind] := *ast_symbol{ref_id, file, name, kind, signature, start_line, end_line}" --params "{}"
+git-ai ai dsr context --json
+git-ai ai dsr generate HEAD
+git-ai ai dsr rebuild-index
+git-ai ai dsr query symbol-evolution "GitAIV2MCPServer" --limit 200 --json
+git-ai ai pack
+git-ai ai unpack
+git-ai ai agent install
+git-ai ai hooks install
+git-ai ai serve
+```
+
+说明：
+- 除 `ai status` 默认输出为人类可读文本外，其余命令输出均为 JSON（便于 Agent/脚本解析）。
+- `ai status --json` 可输出机器可读 JSON。
+- `ai index` 的进度条输出到 stderr，stdout 保持为 JSON（避免破坏管道解析）。
+
+## DSR（按提交、不可变、确定性）
+
+DSR 命令入口为 `git-ai ai dsr ...`，产物位于 `.git-ai/dsr/`。
+
+- `dsr context`：发现 repo root / HEAD / branch，并检测 DSR 目录状态
+- `dsr generate <commit>`：为单个提交生成 DSR（存在且不同会报错，不会覆盖）
+- `dsr rebuild-index`：从 DSR 重建可删的查询加速索引
+- `dsr query symbol-evolution <symbol>`：只读查询；先遍历 Git DAG，再读取 DSR 附着语义；缺失 DSR 会停止并报错
+
+## Agent 一键安装（skills/rules）
+
+将本仓库内置的 Agent 模板（skills/rules）复制到目标仓库的 `.agents/` 目录，便于主流 code agent 识别与加载。
+
+```bash
+cd /path/to/your-repo
+git-ai ai agent install
+git-ai ai agent install --overwrite
+git-ai ai agent install --to /custom/location/.agents
+
+# 可选：安装到 Trae 的 .trae 目录
+git-ai ai agent install --agent trae
+```
+
+## RepoMap（全局鸟瞰，可选）
+
+为了支持类似 aider 的 repomap 能力（重要文件/符号排名、上下文映射、引导 Wiki 关联阅读），repo map 被集成到 **已有检索命令** 中，默认不输出，避免增加输出体积与 token 消耗。
+
+在需要时，显式开启：
+
+```bash
+git-ai ai query "HelloController" --with-repo-map --repo-map-files 20 --repo-map-symbols 5
+git-ai ai semantic "where is auth handled" --with-repo-map
+```
+
+参数说明：
+- `--with-repo-map`：在 JSON 输出中附加 `repo_map` 字段
+- `--repo-map-files <n>`：repo map 展示的文件数量上限（默认 20）
+- `--repo-map-symbols <n>`：每个文件展示的符号上限（默认 5）
+- `--wiki <dir>`：指定 Wiki 目录（默认自动探测 `docs/wiki` 或 `wiki`）
+
+## 符号搜索模式（ai query）
+
+`git-ai ai query` 默认是子串搜索；当你的输入包含 `*` / `?` 时，或显式指定 `--mode`，可以启用更适合 code agent 的搜索模式：
+
+- `--mode substring`：子串匹配（默认）
+- `--mode prefix`：前缀匹配
+- `--mode wildcard`：通配符（`*` 任意串，`?` 单字符）
+- `--mode regex`：正则
+- `--mode fuzzy`：模糊匹配（子序列）
+
+常用参数：
+- `--case-insensitive`：大小写不敏感
+- `--max-candidates <n>`：先拉取候选再过滤的上限（模式为 wildcard/regex/fuzzy 时有用）
+
+## AST 图搜索（CozoDB）
+
+> **实战指南**：觉得命令太抽象？请查看 [AST 图谱实战指南](./graph_scenarios.md) 了解如何查找定义、父类、子类等常见场景。
+
+`git-ai ai index` 会在 `.git-ai/` 下额外维护一份 AST 关系图数据库（默认文件名：`.git-ai/ast-graph.sqlite`）。
+
+图搜索相关命令：
+- `git-ai ai graph find <prefix>`：按符号名前缀（不区分大小写）查找
+- `git-ai ai graph children <id>`：列出包含关系的直接子节点（`id` 可以是 `ref_id` 或 `file_id`）
+- `git-ai ai graph children <file> --as-file`：把 `<file>` 视作 repo 相对路径，自动换算为 `file_id`
+- `git-ai ai graph query "<CozoScript>" --params '<JSON>'`：直接执行 CozoScript 查询
+
+依赖说明：
+- 默认优先使用 `cozo-node`（SQLite 持久化）
+- 若 `cozo-node` 不可用，会回退到 `cozo-lib-wasm`（内存引擎，通过导出文件实现跨进程复用）

package/docs/zh-CN/dsr.md

@@ -0,0 +1,91 @@
+# DSR（Deterministic Semantic Record）
+
+DSR 是一个 **按提交（per-commit）** 的、**不可变（immutable）**、**确定性（deterministic）** 的语义工件：每个 Git commit 对应一份 DSR 文件。DSR 只负责“丰富提交节点的语义”，**永远不定义 Git DAG 的边**。
+
+## 设计约束（不可违反）
+
+- Git commit DAG 是历史与分支的唯一权威来源
+- DSR 按提交生成：一个 commit → 一个 DSR 文件
+- DSR 一旦生成不可修改；若发现冲突，视为系统错误并停止
+- DSR 是规范工件（canonical artifact）；数据库/索引仅是可重建缓存（rebuildable cache）
+- 绝不从语义数据推断 Git 拓扑（父子/分支/合并结构）
+
+冲突优先级：
+
+Git > DSR > Database > Heuristics
+
+缺失数据处理：
+
+- 缓存缺失：从 DSR + Git 重建
+- DSR 缺失：报告并停止（不要推断）
+
+## 存储布局
+
+DSR 相关产物位于仓库根目录：
+
+- `.git-ai/dsr/<commit_hash>.json`：单提交 DSR（规范工件）
+- `.git-ai/dsr/dsr-index.sqlite`：DSR 查询加速索引（可删缓存）
+- `.git-ai/dsr/dsr-index.export.json`：非 SQLite 后端时的导出快照（用于跨进程复用）
+
+## DSR Schema（v1）
+
+必填字段：
+
+- `commit_hash`
+- `affected_symbols`
+- `ast_operations`
+- `semantic_change_type`
+
+可选字段：
+
+- `summary`（默认使用 commit subject）
+- `risk_level`
+
+禁止字段（避免编码拓扑/分支信息）：
+
+- parent commits / branch names / merge topology
+
+## CLI 命令
+
+### Phase 0：上下文发现
+
+```bash
+git-ai ai dsr context --json
+```
+
+产物（JSON）包含：
+
+- `repo_root`
+- `commit_hash`（HEAD commit）
+- `branch` / `detached`
+- `dsr_directory_state`（.git-ai 与 dsr 目录存在性/文件数）
+
+### Phase 2：为单个提交生成 DSR
+
+```bash
+git-ai ai dsr generate <commit>
+```
+
+- `<commit>` 支持任何可解析为 commit 的 rev（例如 `HEAD`、sha、tag）
+- 生成路径固定为 `.git-ai/dsr/<commit_hash>.json`
+- 若文件已存在且内容不同会报错并停止（保证不可变性）
+
+### Phase 3：从 DSR 重建缓存索引
+
+```bash
+git-ai ai dsr rebuild-index
+```
+
+该索引用于加速查询，语义事实不应只存在于数据库中。
+
+### Phase 6：只读查询（Git DAG 先行）
+
+```bash
+git-ai ai dsr query symbol-evolution <symbol> --limit 200 --json
+```
+
+行为要点：
+
+- 先按 `git rev-list --topo-order` 遍历 DAG
+- 每个 commit 再读取对应 DSR 进行语义附着
+- 遇到缺失 DSR 的 commit 会立刻停止并返回错误（不推断）

package/docs/zh-CN/graph_scenarios.md

@@ -0,0 +1,173 @@
+# AST 图谱实战指南
+
+`git-ai ai graph` 命令提供了强大的代码结构查询能力。本文档通过实际场景，介绍如何查找定义、结构、继承关系等。
+
+## 1. 查找定义 (Find Definitions)
+
+### 场景：我知道一个类或方法的名字（或前缀），想找到它在哪里定义。
+
+**命令：**
+```bash
+# 查找名字以 "GitAI" 开头的符号
+git-ai ai graph find "GitAI"
+```
+
+**输出示例：**
+```json
+{
+  "repoRoot": "/path/to/repo",
+  "result": {
+    "headers": ["ref_id", "file", "lang", "name", "kind", "signature", "start_line", "end_line"],
+    "rows": [
+      ["...", "src/mcp/server.ts", "ts", "GitAIV2MCPServer", "class", "class GitAIV2MCPServer", 16, 120]
+    ]
+  }
+}
+```
+
+> **提示**：如果你只记得模糊的名字（如 `*Server`），建议使用 `ai query` 命令配合 wildcard 模式：
+> ```bash
+> git-ai ai query "*Server" --mode wildcard
+> ```
+
+---
+
+## 2. 查看文件结构 (File Structure)
+
+### 场景：我想知道某个文件里定义了哪些类、函数或接口。
+
+**命令：**
+使用 `children` 子命令，并加上 `--as-file` 参数，直接传文件路径：
+
+```bash
+# 查看 src/mcp/server.ts 里的顶层符号
+git-ai ai graph children src/mcp/server.ts --as-file
+```
+
+**输出示例：**
+```json
+{
+  "result": {
+    "headers": ["child_id", "file", "lang", "name", "kind", "signature", "start_line", "end_line"],
+    "rows": [
+      ["...", "src/mcp/server.ts", "ts", "GitAIV2MCPServer", "class", "class GitAIV2MCPServer", 16, 120]
+    ]
+  }
+}
+```
+
+### 场景：我想进一步看某个类里有哪些方法。
+
+**步骤：**
+1. 从上一步结果中复制类的 `child_id`（即 `ref_id`）。
+2. 再次运行 `children` 命令（这次不需要 `--as-file`）。
+
+```bash
+git-ai ai graph children <ref_id_from_previous_step>
+```
+
+---
+
+## 3. 查找继承与实现 (Inheritance & Implementation)
+
+这部分需要使用 `git-ai ai graph query` 执行 CozoScript。CozoScript 是一种类似 Datalog 的逻辑查询语言。
+
+### 场景：查找某个类的所有子类 (Find Subclasses)
+
+假设你想找所有继承自 `BaseCommand` 的类。
+
+**CozoScript:**
+```cozo
+?[name, file, start_line] := 
+  *ast_extends_name{sub_id, super_name: 'BaseCommand'},
+  *ast_symbol{ref_id: sub_id, name, file, lang, kind, signature, start_line, end_line}
+```
+
+**CLI 命令：**
+```bash
+git-ai ai graph query "?[name, file, lang] := *ast_extends_name{sub_id, super_name: 'BaseCommand'}, *ast_symbol{ref_id: sub_id, name, file, lang, kind, signature, start_line, end_line}"
+```
+
+### 场景：查找某个接口的所有实现 (Find Implementations)
+
+假设你想找所有实现了 `Runnable` 接口的类。
+
+**CozoScript:**
+```cozo
+?[name, file] := 
+  *ast_implements_name{sub_id, iface_name: 'Runnable'},
+  *ast_symbol{ref_id: sub_id, name, file, lang, kind, start_line, end_line}
+```
+
+**CLI 命令：**
+```bash
+git-ai ai graph query "?[name, file, lang] := *ast_implements_name{sub_id, iface_name: 'Runnable'}, *ast_symbol{ref_id: sub_id, name, file, lang, kind, signature, start_line, end_line}"
+```
+
+### 场景：查找某个类的父类 (Find Parent Class)
+
+假设你想知道 `MyClass` 继承了谁。
+
+**CozoScript:**
+```cozo
+?[super_name] := 
+  *ast_symbol{ref_id, name: 'MyClass'},
+  *ast_extends_name{sub_id: ref_id, super_name}
+```
+
+---
+
+## 4. 查找引用 (Find References/Usages)
+
+AST 图谱现在支持一部分“引用/调用”能力（基于语法树的启发式抽取，按**名字**关联），可用于快速回答：
+- “这个方法/函数被谁调用？”
+- “从这个方法往下会调用到哪些方法（近似调用链）？”
+- “某个符号名在仓库里有哪些引用位置（call/new/type）？”
+
+### 4.1 查引用位置（按名字）
+
+```bash
+git-ai ai graph refs "MySymbol"
+```
+
+### 4.2 查调用者 / 被调用者（按名字）
+
+```bash
+git-ai ai graph callers "greet"
+git-ai ai graph callees "hello"
+```
+
+### 4.3 近似调用链（按名字 + 深度）
+
+```bash
+# 从 greet 向上找：谁调用了它、再往上是谁调用了调用者...
+git-ai ai graph chain "greet" --direction upstream --depth 3 --lang java
+
+# 从 hello 向下找：hello 里调用了什么、被调用者又调用了什么...
+git-ai ai graph chain "hello" --direction downstream --depth 3 --lang ts
+```
+
+### 性能与准确性提示（很重要）
+
+- `chain` 是“按名字”的启发式调用链：每一跳都会把 `callee_name` 与全仓库同名符号做匹配，跨语言/跨目录也会互相影响
+- 当链路中出现高频通用名字（如 `remove` / `update` / `get` / `list`），同名符号会指数级放大，中间结果暴涨，导致查询变慢
+- 更稳的用法：
+  - 优先用 `callers` 精确定位“谁调用了 X”（一跳）
+  - 调小 `--depth`（建议从 1/2 开始）
+  - 配合 `--limit` 控制返回规模
+  - 明确指定语言，避免跨语言噪声：`--lang java` 或 `--lang ts`
+  - 如果输出里出现大量单字母（常见于压缩/混淆后的前端代码），用 `chain --min-name-len 2` 过滤掉短名字
+
+---
+
+## 附录：数据表结构参考
+
+如果你想编写更复杂的查询，可以参考以下表结构：
+
+- **`ast_symbol`**: `{ ref_id, file, lang, name, kind, signature, start_line, end_line }`
+- **`ast_file`**: `{ file_id, file, lang }`
+- **`ast_contains`**: `{ parent_id, child_id }` （parent_id 可能是 file_id 或 ref_id）
+- **`ast_extends_name`**: `{ sub_id, super_name }`
+- **`ast_implements_name`**: `{ sub_id, iface_name }`
+- **`ast_ref_name`**: `{ from_id, from_lang, name, ref_kind, file, line, col }` （ref_kind: call/new/type）
+- **`ast_call_name`**: `{ caller_id, caller_lang, callee_name, file, line, col }`

package/docs/zh-CN/hooks.md

@@ -0,0 +1,14 @@
+# Hooks 工作流
+
+## 安装
+
+```bash
+cd /path/to/repo
+git-ai ai hooks install
+git-ai ai hooks status
+```
+
+## 行为
+- `pre-commit`：自动 `index --incremental --staged` + `pack`，并把 `.git-ai/meta.json`、`.git-ai/lancedb.tar.gz` 加入暂存区（索引内容以 staged 为准）
+- `pre-push`：再次 `pack`，若归档发生变化则阻止 push，提示先提交归档文件
+- `post-checkout` / `post-merge`：若存在 `.git-ai/lancedb.tar.gz` 则自动 `unpack`

package/docs/zh-CN/manifests.md

@@ -0,0 +1,136 @@
+# Manifest Workspace（`.repo/manifests`）支持（Ref 指针 + 按需索引/查询）
+
+这篇文档说明 `git-ai` 如何在 **Android repo tool** 的 workspace 场景中工作：在 `.../.repo/manifests` 这种 *manifest 仓库* 中，`git-ai` 不会把所有子仓库的索引都塞进 manifest 仓库；而是把 manifest 里的 `<project/>` 视为“ref 指针”，在查询时按需定位/检出对应子仓库，并在子仓库内查询（必要时再构建索引）。
+
+适用目录结构示例：
+
+```text
+workspace/
+  .repo/
+    manifests/          # 运行 git-ai 的位置
+      .git/
+      default.xml
+  project-a/
+    .git/
+    ...
+  project-b/
+    .git/
+    ...
+```
+
+## 背景与目标
+
+在 repo tool workspace 中：
+- **真正的代码**分散在 `workspace/` 下的多个 project 子仓库（`project-a/`、`project-b/`…）
+- **manifest 仓库**位于 `workspace/.repo/manifests`，负责描述 project 列表与 revision
+
+如果把 workspace 下所有源码都索引进 manifest 仓库，会带来：
+- 存储成本高：manifest 仓库的 `.git-ai/` 会膨胀（尤其在多项目 workspace）
+- 性能风险：一次索引要扫描大量目录，且每次增量都集中写到同一个 DB
+
+因此本方案改为：
+- manifest 仓库只索引自身（如需要），不存储所有子仓库索引
+- 子仓库索引由子仓库自己维护（`.git-ai/lancedb/` 或 `.git-ai/lancedb.tar.gz`）
+- 查询时按需切到/拉取对应子仓库，再查询其索引
+
+## 行为概览
+
+当你在 manifest 仓库运行：
+
+```bash
+git-ai ai query SomeClass --limit 20
+```
+
+`git-ai` 会：
+- 解析 manifest（默认 `default.xml`）得到 project 列表（相当于“ref 指针”集合）
+- 对每个 project：
+  - 优先使用 workspace 本地已有目录（`workspace/<project path>`）
+  - 若本地不存在，则克隆到 `workspace-cache`（在 manifest 仓库的 `.git-ai/` 下，不提交）
+  - 切到 manifest 指定的 revision（如果有）
+  - 若子仓库已有索引则直接查询；否则按需构建索引后查询
+
+### 流程图（按需查询）
+
+```mermaid
+graph TD
+  A["用户在 .repo/manifests 运行 git-ai ai query"] --> B["resolveGitRoot 定位 repoRoot"];
+  B --> C["inferWorkspaceRoot: repoRoot 上溯到 workspace 根"];
+  C --> D["解析 default.xml 得到 projects"];
+  D --> E{"project 在 workspace 是否已存在?"};
+  E -->|是| F["直接使用 workspace/{path}"];
+  E -->|否| G["clone 到 repoRoot/.git-ai/workspace-cache/{path}"];
+  F --> H["checkout revision(如有)"];
+  G --> H;
+  H --> I{"子仓库是否已有索引?"};
+  I -->|有| J["直接查询子仓库 refs/chunks"];
+  I -->|无| K["在子仓库内构建索引后再查询"];
+  J --> L["聚合结果输出（带 project 信息）"];
+  K --> L;
+```
+
+## 关键实现点
+
+### 1) 推导 workspaceRoot（workspace 根目录）
+
+判断逻辑：
+- 当 `repoRoot` 的路径中包含 `.repo/manifests` 或 `.repo/manifests.git` 时，认为这是 manifest 仓库
+- 将 `workspaceRoot` 设为 `.repo` 的上一级目录（即 workspace 根）
+
+实现入口：[inferWorkspaceRoot](file:///Users/mars/dev/git-ai/git-ai-cli-v2/src/core/git.ts)
+
+### 2) Manifest 解析（project 列表作为 ref 指针）
+
+当前实现会读取 manifest 仓库中的 `default.xml`（如果没有则尝试其他 `*.xml`），解析：
+- `<project name path remote revision/>`
+- `<remote name fetch/>` 与 `<default remote revision/>`
+
+相关实现：
+- [manifest.ts](file:///Users/mars/dev/git-ai/git-ai-cli-v2/src/core/manifest.ts)
+
+### 3) 子仓库按需检出（workspace 优先，缺失则 cache clone）
+
+- 若 `workspace/<project path>` 已存在且是 git 仓库：直接使用
+- 否则 clone 到 `repoRoot/.git-ai/workspace-cache/<project path>`（该目录不应提交）
+- 若 manifest 提供 revision：切到对应 revision（或 `origin/<revision>`）
+
+相关实现：[workspace.ts](file:///Users/mars/dev/git-ai/git-ai-cli-v2/src/core/workspace.ts)
+
+### 4) 子仓库索引按需使用（优先现有索引，缺失则构建）
+
+查询时针对每个子仓库：
+- 若存在 `.git-ai/lancedb/`：直接打开查询
+- 否则若存在 `.git-ai/lancedb.tar.gz`：先解包再查询
+- 都不存在时：在该子仓库内按需构建索引，再查询
+
+相关实现：
+- [ensureRepoIndexReady](file:///Users/mars/dev/git-ai/git-ai-cli-v2/src/core/workspace.ts)
+- CLI 查询入口：[ai query](file:///Users/mars/dev/git-ai/git-ai-cli-v2/src/commands/query.ts)
+- MCP 符号检索在 manifests 场景下也会走按需查询：[server.ts](file:///Users/mars/dev/git-ai/git-ai-cli-v2/src/mcp/server.ts)
+
+### 5) 存储成本与性能策略
+
+- manifest 仓库只保存“ref 指针”（manifest XML）与少量运行时缓存（workspace-cache），避免把所有子仓库索引集中存储
+- 查询只触达必要的子仓库，并在拿到足够结果后提前停止
+- workspace-cache 放在 `.git-ai/` 下并通过 `.gitignore` 排除，避免污染 manifest 仓库历史
+
+## 使用方式
+
+### 直接在 manifests 仓库查询
+
+```bash
+cd /ABS/PATH/workspace/.repo/manifests
+git-ai ai query SomeClass --limit 20
+```
+
+输出里会包含 `rows[].project` 字段，标明结果来自哪个子仓库（以及是从 workspace 还是 cache 来的）。
+
+### 验证模版
+
+仓库内提供了一个最小模版可以一键生成 workspace 并验证：
+- 文档：[repo-manifest-workspace-template/README.md](file:///Users/mars/dev/git-ai/git-ai-cli-v2/examples/repo-manifest-workspace-template/README.md)
+- 初始化脚本：[init-workspace.mjs](file:///Users/mars/dev/git-ai/git-ai-cli-v2/examples/repo-manifest-workspace-template/init-workspace.mjs)
+
+## 已知限制与后续方向
+
+- 当前 XML 解析为轻量实现，覆盖常见的 `<remote/>`、`<default/>`、`<project/>` 场景；更复杂的 include/override 还未覆盖。
+- 若 manifest 未提供 remote fetch 且 workspace 本地也不存在对应 project 目录，则无法自动 clone。