refactor(mcp): atomic calls via path; remove set_repo

.gitignore

@@ -8,6 +8,9 @@ dist/
 .git-ai/ast-graph.sqlite
 .git-ai/ast-graph.export.json
 .git-ai/._*
+.git-ai/dsr/dsr-index.sqlite
+.git-ai/dsr/dsr-index.export.json
 .tmp-hook-test/
 .vscode/
 .trae/documents/
+.trae/

DEVELOPMENT.md

@@ -76,7 +76,7 @@ git-ai ai hooks status
 git-ai ai serve
 ```
 
-If the host cannot guarantee the working directory points to the repository directory, you can let the Agent call `set_repo({path: ...})` first, or pass `path` in tool parameters.
+MCP tools require `path` in every tool call to select the target repository (atomic, no implicit defaults).
 
 ## Publishing Notes (npm)
 - Ensure `npm run build` has generated `dist/**`

DEVELOPMENT.zh-CN.md

@@ -76,7 +76,7 @@ git-ai ai hooks status
 git-ai ai serve
 ```
 
-如果宿主无法保证工作目录指向仓库目录，可以先让 Agent 调用 `set_repo({path: ...})`，或在工具参数里传 `path`。
+MCP tools 的 `path` 为必传：每次工具调用都必须显式传 `path` 参数来选择目标仓库（调用原子化，无隐式默认）。
 
 ## 发布注意事项（npm）
 - 确保 `npm run build` 已生成 `dist/**`

README.md

@@ -57,11 +57,22 @@ git-ai ai index --overwrite
 git-ai ai query Indexer --limit 10
 git-ai ai semantic "semantic search" --topk 5
 git-ai ai graph find GitAIV2MCPServer
+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 serve
 ```
 
+## DSR (Deterministic Semantic Record)
+
+DSR is a per-commit, immutable, deterministic semantic artifact:
+
+- Canonical files: `.git-ai/dsr/<commit_hash>.json`
+- Databases are rebuildable caches derived from DSR + Git (never the other way around)
+
 ## MCP Server (stdio)
 
 `git-ai` provides an MCP-based stdio Server for Agents/Clients to call as tools:
@@ -98,26 +109,27 @@ git-ai ai serve
 ```
 
 Note:
-- `git-ai ai serve` defaults to using the current directory as the repository location (similar to git usage).
-- If the host cannot guarantee that the MCP process working directory (cwd) points to the repository directory, it is recommended that the Agent execute `set_repo({path: \"/ABS/PATH/TO/REPO\"})` before the first call, or pass the `path` parameter in every tool call.
+- `git-ai ai serve` only starts the MCP stdio server.
+- MCP tools require `path` in every tool call to select the target repository (atomic, no implicit defaults).
 
-## Agent Skills / Rules (Trae)
+## Agent Templates
 
 This repository provides reusable Skill/Rule templates for Agents:
-- Skill: [./.trae/skills/git-ai-mcp/SKILL.md](./.trae/skills/git-ai-mcp/SKILL.md)
-- Rule: [./.trae/rules/git-ai-mcp/RULE.md](./.trae/rules/git-ai-mcp/RULE.md)
+- 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)
 
 Usage:
-- After opening this repository in Trae, the Agent will automatically load Skills under `.trae/skills/**`.
-- When you need to add constraints to the Agent, put the Rule content into your Agent configuration/system rules (or directly reference `.trae/rules/**` in this repository as a source).
+- Install the templates into your target repository (default: `.agents/`).
+- For Trae compatibility, you can install into `.trae/` with `--agent trae`.
 
 One-click install into another repository:
 
 ```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/.trae
+git-ai ai agent install --to /custom/location/.agents
+git-ai ai agent install --agent trae
 ```
 
 ## Git hooks (Rebuild index before commit, verify pack before push, auto unpack on checkout)
@@ -130,7 +142,7 @@ git-ai ai hooks status
 ```
 
 Explanation:
-- `pre-commit`: Automatically `index --overwrite` + `pack`, and add `.git-ai/meta.json` and `.git-ai/lancedb.tar.gz` to the staging area.
+- `pre-commit`: Automatically `index --incremental --staged` + `pack`, and add `.git-ai/meta.json` and `.git-ai/lancedb.tar.gz` to the staging area.
 - `pre-push`: `pack` again, if the archive changes, block the push and prompt to submit the archive file first.
 - `post-checkout` / `post-merge`: If `.git-ai/lancedb.tar.gz` exists, automatically `unpack`.
 

README.zh-CN.md

@@ -57,11 +57,22 @@ git-ai ai index --overwrite
 git-ai ai query Indexer --limit 10
 git-ai ai semantic "semantic search" --topk 5
 git-ai ai graph find GitAIV2MCPServer
+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 serve
 ```
 
+## DSR（Deterministic Semantic Record）
+
+DSR 是按提交（per-commit）、不可变、确定性的语义工件：
+
+- 规范文件：`.git-ai/dsr/<commit_hash>.json`
+- 数据库/索引仅为可删缓存，必须可由 DSR + Git 重建（永远不反向推断 Git DAG）
+
 ## MCP Server（stdio）
 
 `git-ai` 提供一个基于 MCP 的 stdio Server，供 Agent/客户端以工具方式调用：
@@ -98,26 +109,23 @@ git-ai ai serve
 ```
 
 说明：
-- `git-ai ai serve` 默认使用当前目录作为仓库定位起点（类似 git 的用法）。
-- 若宿主无法保证 MCP 进程的工作目录（cwd）指向仓库目录，推荐由 Agent 在首次调用前先执行一次 `set_repo({path: \"/ABS/PATH/TO/REPO\"})`，或在每次 tool 调用里传 `path` 参数。
-
-## Agent Skills / Rules（Trae）
+- `git-ai ai serve` 仅负责启动 MCP stdio server。
+- MCP tools 的 `path` 为必传：每次 tool 调用都必须显式传 `path` 参数来选择目标仓库（调用原子化，无隐式默认）。
 
-本仓库提供了 Agent 可直接复用的 Skill/Rule 模版：
-- Skill： [./.trae/skills/git-ai-mcp/SKILL.md](./.trae/skills/git-ai-mcp/SKILL.md)
-- Rule： [./.trae/rules/git-ai-mcp/RULE.md](./.trae/rules/git-ai-mcp/RULE.md)
+## Agent 模版（skills/rules）
 
-使用方式：
-- 在 Trae 中打开本仓库后，Agent 会自动加载 `.trae/skills/**` 下的 Skill。
-- 需要给 Agent 加约束时，把 Rule 内容放到你的 Agent 配置/系统规则中（也可以直接引用本仓库的 `.trae/rules/**` 作为规范来源）。
+本仓库提供了可复用的 Skill/Rule 模版：
+- 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)
 
 一键安装到其它仓库：
 
 ```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/.trae
+git-ai ai agent install --to /custom/location/.agents
+git-ai ai agent install --agent trae
 ```
 
 ## Git hooks（提交前重建索引，push 前打包校验，checkout 自动解包）
@@ -130,7 +138,7 @@ git-ai ai hooks status
 ```
 
 说明：
-- `pre-commit`：自动 `index --overwrite` + `pack`，并把 `.git-ai/meta.json` 与 `.git-ai/lancedb.tar.gz` 加入暂存区。
+- `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`。
 

assets/hooks/pre-commit

@@ -11,7 +11,7 @@ if ! command -v git-ai >/dev/null 2>&1; then
   exit 0
 fi
 
-git-ai ai index --overwrite -p "$ROOT" >/dev/null
+git-ai ai index --incremental --staged -p "$ROOT" >/dev/null
 git-ai ai pack -p "$ROOT" >/dev/null
 
 git add .git-ai/meta.json .git-ai/lancedb.tar.gz || true

docs/README.md

@@ -11,13 +11,16 @@ This collects all documentation for `git-ai`.
 ### Core Goals
 - Store structured code repository indexes under `.git-ai/`, shareable via archive `.git-ai/lancedb.tar.gz`.
 - Enable Agents to hit symbols/snippets via MCP tools at low cost, then read files as needed.
+- Persist per-commit semantic change as DSR (immutable, deterministic), and rebuild caches from it.
 
 ### Important Directories
 - `.git-ai/meta.json`: Index metadata (locally generated, usually not committed).
 - `.git-ai/lancedb/`: Local vector index directory (usually not committed).
 - `.git-ai/lancedb.tar.gz`: Archived index (can be committed/tracked via git-lfs).
 - `.git-ai/ast-graph.sqlite`: AST graph database (CozoDB).
 - `.git-ai/ast-graph.export.json`: AST graph export snapshot (for non-SQLite backend cross-process reuse).
+- `.git-ai/dsr/<commit_hash>.json`: Per-commit DSR (canonical artifact, immutable).
+- `.git-ai/dsr/dsr-index.sqlite`: DSR query accelerator (rebuildable cache from DSR + Git).
 
 ## Directory
 
@@ -29,6 +32,7 @@ This collects all documentation for `git-ai`.
 - [MCP Server Integration](./zh-CN/mcp.md) (Chinese)
 - [Manifest Workspace Support](./zh-CN/manifests.md) (Chinese)
 - [Troubleshooting](./zh-CN/troubleshooting.md) (Chinese)
+- [DSR (Deterministic Semantic Record)](./zh-CN/dsr.md) (Chinese)
 
 ### Advanced & Principles
 - [Advanced: Index Archiving & LFS](./zh-CN/advanced.md) (Chinese)

docs/zh-CN/DESIGN.md

@@ -5,6 +5,7 @@
 - 引入 SQ8（8-bit 标量量化）降低向量存储体积。
 - 引入内容哈希去重：相同内容只存一份向量，多处引用仅存引用关系。
 - 索引口径：仅针对当前 checkout 的 HEAD 工作区；历史版本由 Git 负责管理（通过 checkout 获得对应索引快照）。
+- 提供按提交的 DSR（Deterministic Semantic Record）作为语义工件：按提交、不可变、确定性；数据库仅作可重建缓存。
 
 ## 2. 存储布局
 索引产物放在仓库根目录：
@@ -15,6 +16,10 @@
   - `ast-graph.export.json`：AST 图导出快照（仅在非 SQLite 后端时用于跨进程复用）
   - `meta.json`：索引元信息（维度、编码、构建时间等）
 
+DSR 产物（按提交，规范工件）：
+- `.git-ai/dsr/<commit_hash>.json`：单提交 DSR（不可变、确定性）
+- `.git-ai/dsr/dsr-index.sqlite`：DSR 查询加速索引（可删缓存，可由 DSR + Git 重建）
+
 ## 3. 数据模型（两张表）
 
 ### 3.1 chunks（去重后的内容向量表）
@@ -77,3 +82,21 @@
 - `pre-push`：再次打包并校验归档未发生变化；若变化则阻止 push，提示先提交归档文件。
 - `post-checkout` / `post-merge`：若存在 `.git-ai/lancedb.tar.gz`，自动解包到 `.git-ai/lancedb/`。
 - 安装方式：在仓库中执行 `git-ai ai hooks install`（写入 .githooks/* 并设置 core.hooksPath=.githooks）。
+
+## 8. DSR（Deterministic Semantic Record）
+
+DSR 用于固化“每个提交的语义变化”，并严格遵守：
+
+- Git DAG 是历史/分支的唯一权威来源（DSR 只 enrich 节点，不定义边）
+- 一次提交 → 一份 DSR 文件（`.git-ai/dsr/<commit_hash>.json`）
+- DSR 一旦生成不可覆盖；若已存在且内容不同应停止并报错
+- 任何数据库/索引必须可由 DSR + Git 重建（缓存可删）
+
+CLI 入口：
+
+- `git-ai ai dsr context`
+- `git-ai ai dsr generate <commit>`
+- `git-ai ai dsr rebuild-index`
+- `git-ai ai dsr query symbol-evolution <symbol>`
+
+更详细说明见：[DSR 文档](./dsr.md)

docs/zh-CN/README.md

@@ -13,13 +13,16 @@
 ### 核心目标
 - 把代码仓的结构化索引放在 `.git-ai/` 下，并可通过归档文件 `.git-ai/lancedb.tar.gz` 分享
 - 让 Agent 通过 MCP tools 低成本命中符号/片段，再按需读取文件
+- 把每个提交的语义变化固化为 DSR（按提交、不可变、确定性），并可据此重建缓存
 
 ### 重要目录
 - `.git-ai/meta.json`：索引元数据（本地生成，通常不提交）
 - `.git-ai/lancedb/`：本地向量索引目录（通常不提交）
 - `.git-ai/lancedb.tar.gz`：归档后的索引（可提交/可用 git-lfs 追踪）
 - `.git-ai/ast-graph.sqlite`：AST 图数据库（CozoDB）
 - `.git-ai/ast-graph.export.json`：AST 图导出快照（用于非 SQLite 后端跨进程复用）
+- `.git-ai/dsr/<commit_hash>.json`：单提交 DSR（规范工件，按提交、不可变）
+- `.git-ai/dsr/dsr-index.sqlite`：DSR 查询加速索引（可删缓存，可由 DSR + Git 重建）
 
 ## 目录
 
@@ -31,6 +34,7 @@
 - [MCP Server 接入](./mcp.md)
 - [Manifest Workspace 支持](./manifests.md)
 - [排障](./troubleshooting.md)
+- [DSR（Deterministic Semantic Record）](./dsr.md)
 
 ### 进阶与原理
 - [进阶：索引归档与 LFS](./advanced.md)

docs/zh-CN/architecture_explained.md

@@ -104,3 +104,13 @@
 `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)