@mars167/git-ai 2.3.0

package/docs/zh-CN/mcp.md

@@ -0,0 +1,205 @@
+# MCP Server 接入
+
+`git-ai` 提供了一个基于 MCP (Model Context Protocol) 的 stdio Server，供 Agent (如 Claude Desktop, Trae 等) 调用，赋予 Agent "理解代码库"的能力。
+
+## 启动
+
+在任意目录执行：
+
+```bash
+git-ai ai serve
+```
+
+该进程是 stdio 模式（会等待客户端连接）。你可以把它配置到支持 MCP 的客户端里。
+
+## 工具列表
+
+### 仓库管理
+- `get_repo({ path })`：返回指定 `path` 对应的仓库根目录与扫描根目录（调试用）
+
+### 索引管理
+- `check_index({ path })`：检查索引结构是否与当前版本一致（不一致需重建索引）
+- `rebuild_index({ path, dim?, overwrite? })`：重建全量索引（写入 `.git-ai/`；Risk: high）
+- `pack_index({ path, lfs? })`：打包索引为 `.git-ai/lancedb.tar.gz`（可选启用 git-lfs track）
+- `unpack_index({ path })`：解包索引归档
+
+### 检索
+- `search_symbols({ path, query, mode?, case_insensitive?, max_candidates?, limit?, lang?, with_repo_map?, repo_map_max_files?, repo_map_max_symbols?, wiki_dir? })`：符号检索（lang: auto/all/java/ts/python/go/rust/c/markdown/yaml；可选附带 repo_map）
+- `semantic_search({ path, query, topk?, lang?, with_repo_map?, repo_map_max_files?, repo_map_max_symbols?, wiki_dir? })`：基于 LanceDB + SQ8 的语义检索（lang: auto/all/java/ts/python/go/rust/c/markdown/yaml；可选附带 repo_map）
+- `repo_map({ path, max_files?, max_symbols?, wiki_dir? })`：生成 repo map（重要文件/符号排名、引导 Wiki 阅读）
+- `ast_graph_find({ path, prefix, limit?, lang? })`：按名字前缀查找符号定义（大小写不敏感；lang: auto/all/java/ts）
+- `ast_graph_children({ path, id, as_file? })`：列出包含关系的直接子节点（文件→顶层符号、类→方法等）
+- `ast_graph_refs({ path, name, limit?, lang? })`：按名字查引用位置（call/new/type；lang: auto/all/java/ts）
+- `ast_graph_callers({ path, name, limit?, lang? })`：按名字查调用者（callee name；lang: auto/all/java/ts）
+- `ast_graph_callees({ path, name, limit?, lang? })`：按名字查被调用者（caller name；lang: auto/all/java/ts）
+- `ast_graph_chain({ path, name, direction?, max_depth?, limit?, lang? })`：按名字查调用链路（upstream/downstream，最大深度；lang: auto/all/java/ts）
+- `ast_graph_query({ path, query, params? })`：对 AST 图数据库执行 CozoScript 查询（进阶）
+
+### 文件读取
+- `list_files({ path, pattern?, limit? })`：按 glob 列文件（默认忽略 node_modules, .git 等）
+- `read_file({ path, file, start_line?, end_line? })`：按行读取文件片段
+
+### DSR (Deterministic Semantic Record)
+- `dsr_context({ path })`：获取仓库 Git 上下文和 DSR 目录状态
+  - 返回：commit_hash, repo_root, branch, detached, dsr_directory_state
+- `dsr_generate({ path, commit })`：为指定提交生成 DSR
+  - 返回：commit_hash, file_path, existed, counts, semantic_change_type, risk_level
+- `dsr_rebuild_index({ path })`：从 DSR 文件重建索引，加速查询
+  - 返回：enabled, engine, dbPath, counts
+- `dsr_symbol_evolution({ path, symbol, start?, all?, limit?, contains? })`：追溯符号变更历史
+  - 返回：ok, hits（包含 commit_hash, semantic_change_type, risk_level, operations）
+
+## DSR 使用示例
+
+获取仓库 Git 状态和 DSR 情况：
+
+```js
+dsr_context({ path: "/ABS/PATH/TO/REPO" })
+```
+
+为最近几次提交生成 DSR：
+
+```js
+dsr_generate({ path: "/ABS/PATH/TO/REPO", commit: "HEAD" })
+dsr_generate({ path: "/ABS/PATH/TO/REPO", commit: "HEAD~1" })
+```
+
+查询某个函数的变更历史：
+
+```js
+dsr_symbol_evolution({ path: "/ABS/PATH/TO/REPO", symbol: "handleRequest", limit: 50 })
+```
+
+模糊匹配符号名称：
+
+```js
+dsr_symbol_evolution({ path: "/ABS/PATH/TO/REPO", symbol: "Request", contains: true, limit: 100 })
+```
+
+## AST 图查询示例
+
+列出指定文件里的顶层符号（推荐：无需手动算 file_id）：
+
+```js
+ast_graph_children({ path: "/ABS/PATH/TO/REPO", id: "src/mcp/server.ts", as_file: true })
+```
+
+查询某个方法/函数的调用者（推荐：用 callers/callees/chain，不用手写 CozoScript）：
+
+```js
+ast_graph_callers({ path: "/ABS/PATH/TO/REPO", name: "greet", limit: 50 })
+ast_graph_chain({ path: "/ABS/PATH/TO/REPO", name: "greet", direction: "upstream", max_depth: 3 })
+```
+
+列出指定文件里的顶层符号（进阶：直接写 CozoScript，需要 file_id）：
+
+```cozo
+?[file_id] <- [[$file_id]]
+?[child_id, name, kind, start_line, end_line] :=
+  *ast_contains{parent_id: file_id, child_id},
+  *ast_symbol{ref_id: child_id, file, name, kind, signature, start_line, end_line}
+```
+
+## 推荐调用方式（让 Agent 自动传对路径）
+- MCP tools 的 `path` 为必传：每次工具调用都必须显式传 `path: "/ABS/PATH/TO/REPO"`（保证调用原子性）
+
+## RepoMap 使用建议
+
+repo map 用于给 Agent 一个"全局鸟瞰 + 导航入口"（重要文件/符号 + Wiki 关联），建议作为分析前置步骤：
+
+```js
+repo_map({ path: "/ABS/PATH/TO/REPO", max_files: 20, max_symbols: 5 })
+```
+
+如果你希望在一次检索结果里顺带附加 repo map（默认关闭，避免输出膨胀）：
+
+```js
+search_symbols({ path: "/ABS/PATH/TO/REPO", query: "Foo", limit: 20, with_repo_map: true, repo_map_max_files: 20, repo_map_max_symbols: 5 })
+semantic_search({ path: "/ABS/PATH/TO/REPO", query: "where is auth handled", topk: 5, with_repo_map: true })
+```
+
+## Agent Skills / Rules
+
+本仓库提供了 Agent 可直接复用的 Skill/Rule 模板，旨在让 Agent 能够遵循最佳实践来使用上述工具。
+
+这些模板文档（Markdown/YAML）会被索引，便于 Agent 通过 `semantic_search` 检索 MCP 规则与技能说明。
+
+### YAML 格式模板
+
+- **Skill**: [`templates/agents/common/skills/git-ai/skill.yaml`](../../templates/agents/common/skills/git-ai/skill.yaml) - 指导 Agent 如何使用 git-ai 的 Git-native 语义体系（包含 DSR 约束）与 MCP 工具
+  - 包含：触发条件、工作流步骤、工具定义、输出要求、常见陷阱
+  
+- **Rule**: [`templates/agents/common/rules/git-ai.yaml`](../../templates/agents/common/rules/git-ai.yaml) - 约束 Agent 使用 git-ai MCP 的行为
+  - 包含：必须遵守的规则、推荐策略、禁止事项、Git Hooks 规则、Manifest Workspace 规则
+
+### Markdown 模版（便于直接阅读/复制）
+
+- **Skill**: [`templates/agents/common/skills/git-ai-mcp/SKILL.md`](../../templates/agents/common/skills/git-ai-mcp/SKILL.md)
+- **Rule**: [`templates/agents/common/rules/git-ai-mcp/RULE.md`](../../templates/agents/common/rules/git-ai-mcp/RULE.md)
+
+### 安装到 Trae
+
+将本仓库的 Skills 和 Rules 安装到当前项目的 `.agents` 目录（默认）：
+
+```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` 目录：
+
+```bash
+git-ai ai agent install --agent trae
+```
+
+### Skill 工作流概览
+
+根据 `skill.yaml`，推荐的工作流程：
+
+1. **首次接触仓库** - 使用 `repo_map` 获取全局视图
+2. **检查索引状态** - 使用 `check_index`，必要时 `rebuild_index`
+3. **定位目标代码** - 使用 `search_symbols` 或 `semantic_search`
+4. **理解代码关系** - 使用 `ast_graph_callers/callees/chain`
+5. **追溯变更历史** - 使用 `dsr_symbol_evolution`
+6. **精读代码** - 使用 `read_file` 读取关键片段
+7. **提供建议** - 基于完整理解给出修改建议
+
+### Rule 约束概览
+
+根据 `rule.yaml`，Agent 必须遵守：
+
+- **explicit_path**: 每次调用必须显式传 `path` 参数
+- **check_index_first**: 符号搜索前必须检查索引
+- **understand_before_modify**: 修改前必须先理解实现
+- **use_dsr_for_history**: 追溯历史必须使用 DSR 工具
+- **respect_dsr_risk**: 重视 DSR 报告的 high 风险变更
+
+文档/规则检索建议：
+- 当问题涉及 MCP/Skill/Rule 时，先用 `semantic_search` 定位对应文档片段，再给出结论。
+
+禁止事项包括：
+- 假设符号位置而不搜索
+- 直接修改未读过的文件
+- 手动解析 git 历史
+- 在索引缺失时进行符号搜索
+- 省略 `path` 参数
+
+## DSR 与 MCP 的关系
+
+- **MCP tools** 主要覆盖"索引（.git-ai）构建与检索"，用于让 Agent 低成本定位证据
+- **DSR** 是"按提交的语义工件（.git-ai/dsr）"，用于语义历史/演化类查询
+- DSR 是 per-commit、immutable、deterministic 的，可用于精确追溯符号变更
+- 任何历史遍历都必须从 Git DAG 出发（DSR 只 enrich 节点，不定义边）
+
+DSR 相关命令见：[DSR 文档](./dsr.md)
+
+## 输出要求
+
+Agent 使用 git-ai MCP 工具时应遵循：
+
+1. **先给结论，再给证据** - 先总结发现，再提供详细位置
+2. **使用 IDE 可点击链接** - 格式：`file:///path/to/file#L10-L20`
+3. **最小改动原则** - 建议修改时避免引入新依赖
+4. **证据必须基于 read_file** - 不要基于假设或猜测

package/docs/zh-CN/quickstart.md

@@ -0,0 +1,35 @@
+# 安装与快速开始
+
+## 全局安装
+
+```bash
+npm i -g git-ai
+```
+
+## 在任意仓库生成索引
+
+```bash
+cd /path/to/repo
+git-ai ai status
+git-ai ai index --overwrite
+```
+
+后续如果你只想对变更文件做快速更新（例如配合 git hooks 在提交前重建索引），可以使用增量模式：
+
+```bash
+git-ai ai index --incremental --staged
+```
+
+## 语义检索/符号检索
+
+```bash
+git-ai ai query Indexer --limit 10
+git-ai ai semantic "where do we open lancedb" --topk 5
+```
+
+## 归档与分享
+
+```bash
+git-ai ai pack
+git-ai ai unpack
+```

package/docs/zh-CN/rules.md

@@ -0,0 +1,7 @@
+# Rules
+
+## 规则
+- 优先用 git-ai MCP；若 `index_status` 可用先检查；不可用才用传统命令。
+- 索引只针对当前 HEAD；不在查询接口显式建模版本/分支。
+- 索引数据可被 Git 管理；不写入敏感信息。
+- TypeScript strict；不引入外部 embedding；CLI 输出尽量 JSON。

package/docs/zh-CN/technical-details.md

@@ -0,0 +1,454 @@
+# 技术细节
+
+本文档包含 git-ai 的详细技术说明，适合需要深入了解实现细节的开发者。
+
+## Git 代理模式
+
+`git-ai` 默认行为与 `git` 保持一致，可以作为 `git` 的直接替代品：
+
+```bash
+git-ai init
+git-ai status
+git-ai add -A
+git-ai commit -m "msg"
+git-ai push -u origin main
+```
+
+所有不包含 `ai` 子命令的调用都会被转发到系统 `git`。
+
+## AI 子命令完整列表
+
+所有 AI 相关能力放在 `git-ai ai` 下：
+
+### 索引管理
+
+```bash
+# 查看索引状态
+git-ai ai status
+
+# 重建索引（覆盖模式）
+git-ai ai index --overwrite
+
+# 增量索引（仅索引暂存区文件）
+git-ai ai index --incremental --staged
+```
+
+### 查询操作
+
+```bash
+# 符号检索（支持多种模式）
+git-ai ai query Indexer --limit 10
+
+# 语义搜索
+git-ai ai semantic "semantic search" --topk 5
+
+# AST 图查询
+git-ai ai graph find GitAIV2MCPServer
+git-ai ai graph callers functionName
+git-ai ai graph callees functionName
+git-ai ai graph chain functionName --max-depth 3
+```
+
+### DSR 操作
+
+```bash
+# 获取 Git 上下文和 DSR 状态
+git-ai ai dsr context --json
+
+# 为指定提交生成 DSR
+git-ai ai dsr generate HEAD
+
+# 从 DSR 文件重建索引
+git-ai ai dsr rebuild-index
+
+# 查询符号演变历史
+git-ai ai dsr query symbol-evolution GitAIV2MCPServer --limit 200 --json
+```
+
+### 索引打包
+
+```bash
+# 打包索引归档
+git-ai ai pack
+
+# 使用 Git LFS 打包
+git-ai ai pack --lfs
+
+# 解包索引归档
+git-ai ai unpack
+```
+
+### MCP Server
+
+```bash
+# 启动 MCP Server（stdio 模式）
+git-ai ai serve
+```
+
+## DSR（Deterministic Semantic Record）
+
+DSR 是按提交（per-commit）、不可变、确定性的语义工件。
+
+### 核心特性
+
+- **按提交存储**：每个 Git 提交对应一个 DSR 文件
+- **不可变性**：DSR 文件一旦生成永不修改
+- **确定性**：相同的代码和提交总是生成相同的 DSR
+- **可重建**：数据库/索引仅为可删缓存，必须可由 DSR + Git 重建
+
+### 文件结构
+
+```
+.git-ai/
+├── dsr/
+│   ├── <commit_hash_1>.json
+│   ├── <commit_hash_2>.json
+│   └── ...
+├── lancedb/           # 向量数据库（可删缓存）
+├── cozodb/            # 图数据库（可删缓存）
+├── lancedb.tar.gz     # 索引归档
+└── meta.json          # 元数据
+```
+
+### DSR 文件格式
+
+每个 DSR 文件包含该提交的完整语义信息：
+
+```json
+{
+  "commit_hash": "abc123...",
+  "timestamp": "2024-01-01T00:00:00Z",
+  "files": [
+    {
+      "path": "src/main.ts",
+      "symbols": [
+        {
+          "name": "functionName",
+          "kind": "function",
+          "location": {"line": 10, "column": 0},
+          "signature": "functionName(arg1: string): void"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## MCP Server 详细说明
+
+### 工具列表
+
+`git-ai ai serve` 提供以下 MCP 工具：
+
+#### 1. `check_index`
+
+检查索引是否就绪。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+
+**返回**：
+```json
+{
+  "ok": true,
+  "indexed": true,
+  "commit_hash": "abc123...",
+  "file_count": 1234,
+  "symbol_count": 5678
+}
+```
+
+#### 2. `repo_map`
+
+获取仓库全局视图。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `max_files` (number, optional): 最大文件数，默认 20
+- `max_symbols` (number, optional): 每个文件最大符号数，默认 5
+
+#### 3. `search_symbols`
+
+符号检索（支持多种模式）。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `query` (string, required): 查询字符串
+- `mode` (string, optional): 搜索模式，可选值：`substring`、`prefix`、`wildcard`、`regex`、`fuzzy`，默认 `substring`
+- `limit` (number, optional): 返回结果数，默认 50
+
+#### 4. `semantic_search`
+
+基于 LanceDB + SQ8 的语义检索。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `query` (string, required): 自然语言查询
+- `topk` (number, optional): 返回结果数，默认 10
+
+#### 5. `ast_graph_query`
+
+基于 CozoDB 的 AST 图查询（CozoScript）。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `query` (string, required): CozoScript 查询语句
+- `params` (object, optional): 查询参数
+
+#### 6. `ast_graph_find`
+
+按名称前缀查找符号。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `prefix` (string, required): 符号名前缀
+- `limit` (number, optional): 返回结果数，默认 50
+
+#### 7. `ast_graph_callers`
+
+查找函数调用者。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `name` (string, required): 函数名
+- `limit` (number, optional): 返回结果数，默认 200
+
+#### 8. `ast_graph_callees`
+
+查找函数调用的其他函数。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `name` (string, required): 函数名
+- `limit` (number, optional): 返回结果数，默认 200
+
+#### 9. `ast_graph_chain`
+
+追踪完整调用链。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `name` (string, required): 函数名
+- `direction` (string, optional): 追踪方向，可选值：`downstream`、`upstream`，默认 `downstream`
+- `max_depth` (number, optional): 最大深度，默认 3
+- `limit` (number, optional): 返回结果数，默认 500
+
+#### 10. `read_file`
+
+读取文件内容。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `file` (string, required): 文件相对路径
+- `start_line` (number, optional): 起始行号，默认 1
+- `end_line` (number, optional): 结束行号，默认 200
+
+#### 11. `dsr_context`
+
+获取仓库 Git 上下文和 DSR 目录状态。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+
+**返回**：
+```json
+{
+  "ok": true,
+  "commit_hash": "abc123...",
+  "repo_root": "/path/to/repo",
+  "branch": "main",
+  "detached": false,
+  "dsr_directory_state": {
+    "total_commits": 100,
+    "indexed_commits": 95,
+    "missing_commits": ["def456...", "ghi789..."]
+  }
+}
+```
+
+#### 12. `dsr_generate`
+
+为指定提交生成 DSR。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `commit` (string, optional): 提交哈希，默认 HEAD
+
+#### 13. `dsr_rebuild_index`
+
+从 DSR 文件重建索引。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+
+#### 14. `dsr_symbol_evolution`
+
+追溯符号变更历史。
+
+**参数**：
+- `path` (string, required): 仓库根路径
+- `symbol` (string, required): 符号名
+- `start` (string, optional): 起始提交哈希
+- `all` (boolean, optional): 是否返回所有历史，默认 false
+- `limit` (number, optional): 返回结果数，默认 200
+- `contains` (string, optional): 仅返回包含此提交的分支
+
+### 调用约定
+
+**重要**：所有 MCP 工具调用必须显式传递 `path` 参数。
+
+```json
+{
+  "name": "search_symbols",
+  "arguments": {
+    "path": "/absolute/path/to/repo",
+    "query": "functionName"
+  }
+}
+```
+
+禁止依赖进程状态或工作目录隐式推断仓库位置。
+
+## Git Hooks 详细说明
+
+### 安装 Hooks
+
+```bash
+git-ai ai hooks install
+```
+
+### Hook 行为
+
+#### pre-commit
+
+自动执行以下操作：
+1. 增量索引暂存区文件：`index --incremental --staged`
+2. 打包索引：`pack`
+3. 将 `.git-ai/meta.json` 与 `.git-ai/lancedb.tar.gz` 加入暂存区
+
+**注意**：索引内容以暂存区为准，确保提交的索引与代码一致。
+
+#### pre-push
+
+再次执行 `pack`，若归档发生变化则阻止 push，提示先提交归档文件。
+
+这确保了每次 push 都包含最新的索引归档。
+
+#### post-checkout / post-merge
+
+若存在 `.git-ai/lancedb.tar.gz` 则自动执行 `unpack`。
+
+这确保了切换分支或合并后，索引自动更新。
+
+### 查看 Hook 状态
+
+```bash
+git-ai ai hooks status
+```
+
+## Git LFS 集成
+
+### 为什么需要 Git LFS
+
+索引归档 `.git-ai/lancedb.tar.gz` 可能较大（取决于项目规模），直接存入 Git 历史会导致：
+- 仓库体积膨胀
+- 克隆速度变慢
+- Git 操作性能下降
+
+使用 Git LFS 可以有效管理这些大文件。
+
+### 开启 Git LFS（一次性）
+
+```bash
+# 安装 Git LFS（如果未安装）
+git lfs install
+
+# 跟踪索引归档
+git lfs track ".git-ai/lancedb.tar.gz"
+
+# 提交 .gitattributes
+git add .gitattributes
+git commit -m "chore: track lancedb archive via git-lfs"
+```
+
+### 使用 git-ai 触发 LFS
+
+```bash
+# 打包并自动使用 LFS（如果已安装 git-lfs）
+git-ai ai pack --lfs
+```
+
+### 克隆/切分支后
+
+如果你环境设置了 `GIT_LFS_SKIP_SMUDGE=1`，或发现 `.git-ai/lancedb.tar.gz` 不是有效的 gzip 文件：
+
+```bash
+git lfs pull
+```
+
+## Agent 模版详细说明
+
+### Skill 模版
+
+Skill 模版定义了 Agent 如何使用 git-ai 工具的最佳实践。
+
+**位置**：`templates/agents/common/skills/git-ai-mcp/SKILL.md`
+
+**核心内容**：
+- 推荐工作流程（7 步）
+- 工具选择指南
+- 最佳实践
+- 常见陷阱
+
+### Rule 模版
+
+Rule 模版定义了 Agent 使用 git-ai 工具时的行为约束。
+
+**位置**：`templates/agents/common/rules/git-ai-mcp/RULE.md`
+
+**核心内容**：
+- 必须遵守的规则（must_follow）
+- 推荐的做法（recommended）
+- 禁止的行为（prohibited）
+- 工具使用约束（tool_usage_constraints）
+
+### 安装 Agent 模版
+
+```bash
+# 安装到当前仓库的默认位置
+git-ai ai agent install
+
+# 覆盖已存在的模版
+git-ai ai agent install --overwrite
+
+# 安装到自定义位置
+git-ai ai agent install --to /custom/location/.agents
+
+# 为特定 Agent 安装（如 Trae）
+git-ai ai agent install --agent trae
+```
+
+## 性能指标
+
+### 索引速度
+
+- 1k 文件：< 5 秒
+- 10k 文件：< 30 秒
+- 100k 文件：< 5 分钟
+
+### 查询速度
+
+- 符号检索：< 10ms
+- 语义搜索：< 100ms
+- AST 图查询：< 50ms
+
+### 存储占用
+
+- DSR 文件：约 1-5 MB / 1k 文件
+- LanceDB 索引：约 10-50 MB / 1k 文件
+- CozoDB 索引：约 5-20 MB / 1k 文件
+- 打包归档：约 15-75 MB / 1k 文件
+
+## 故障排查
+
+详见 [故障排查指南](./troubleshooting.md)。