From dfac4501fff5e0bed31479e1645b6c0645eab142 Mon Sep 17 00:00:00 2001 From: mars167 Date: Thu, 29 Jan 2026 02:17:09 +0800 Subject: [PATCH 1/2] chore(release): v2.0.0 --- .git-ai/lancedb.tar.gz | 4 ++-- package-lock.json | 4 ++-- package.json | 2 +- src/mcp/server.ts | 2 +- templates/agents/common/rules/git-ai.yaml | 2 +- templates/agents/common/skills/git-ai/skill.yaml | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.git-ai/lancedb.tar.gz b/.git-ai/lancedb.tar.gz index 849977b..55664d2 100644 --- a/.git-ai/lancedb.tar.gz +++ b/.git-ai/lancedb.tar.gz @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:ace72b3025698c44f30a2c2813b8fc80af0d54fa2e70f5ae028bf9ead7bacb6e -size 84376 +oid sha256:6f1754b2ace576e4b8a3325726acddb2ebefb7c18e2495b270a8306526c8e116 +size 84375 diff --git a/package-lock.json b/package-lock.json index dae70b0..cf210ac 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "git-ai", - "version": "1.1.2", + "version": "2.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "git-ai", - "version": "1.1.2", + "version": "2.0.0", "license": "MIT", "dependencies": { "@lancedb/lancedb": "0.22.3", diff --git a/package.json b/package.json index 56a76bf..c09d4b4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "git-ai", - "version": "1.1.2", + "version": "2.0.0", "main": "dist/index.js", "bin": { "git-ai": "dist/bin/git-ai.js" diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 70985d2..99b8150 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -33,7 +33,7 @@ export class GitAIV2MCPServer { this.startDir = path.resolve(startDir); this.options = options; this.server = new Server( - { name: 'git-ai-v2', version: '1.1.2' }, + { name: 'git-ai-v2', version: '2.0.0' }, { capabilities: { tools: {} } } ); this.setupHandlers(); diff --git a/templates/agents/common/rules/git-ai.yaml b/templates/agents/common/rules/git-ai.yaml index 9593199..b630e58 100644 --- a/templates/agents/common/rules/git-ai.yaml +++ b/templates/agents/common/rules/git-ai.yaml @@ -1,5 +1,5 @@ name: trae-dsr -version: "1.1.2" +version: "2.0.0" description: | Non-negotiable constraints for a Git-native, decentralized semantic indexing system. Enforces DSR determinism/immutability, canonical-vs-cache boundaries, and Git DAG authority. diff --git a/templates/agents/common/skills/git-ai/skill.yaml b/templates/agents/common/skills/git-ai/skill.yaml index ae8a564..d3c6cb8 100644 --- a/templates/agents/common/skills/git-ai/skill.yaml +++ b/templates/agents/common/skills/git-ai/skill.yaml @@ -1,5 +1,5 @@ name: trae-dsr -version: "1.1.2" +version: "2.0.0" role: | You are Trae, an autonomous code agent implementing a Git-native, decentralized semantic indexing system. From d414d731d411d9cbee9c3e8e3f467b365146c614 Mon Sep 17 00:00:00 2001 From: mars167 Date: Thu, 29 Jan 2026 23:39:27 +0800 Subject: [PATCH 2/2] feat(mcp): add DSR tools; refactor agent skills/rules --- .git-ai/lancedb.tar.gz | 4 +- docs/zh-CN/mcp.md | 76 +++-- src/mcp/server.ts | 116 +++++++ .../agents/common/rules/git-ai-mcp/RULE.md | 69 ++++- templates/agents/common/rules/git-ai.yaml | 260 ++++++++-------- .../agents/common/skills/git-ai-mcp/SKILL.md | 148 +++++++-- .../agents/common/skills/git-ai/skill.yaml | 284 ++++++++---------- 7 files changed, 602 insertions(+), 355 deletions(-) diff --git a/.git-ai/lancedb.tar.gz b/.git-ai/lancedb.tar.gz index 55664d2..b369b10 100644 --- a/.git-ai/lancedb.tar.gz +++ b/.git-ai/lancedb.tar.gz @@ -1,3 +1,3 @@ version https://git-lfs.github.com/spec/v1 -oid sha256:6f1754b2ace576e4b8a3325726acddb2ebefb7c18e2495b270a8306526c8e116 -size 84375 +oid sha256:0b2fcae5b5ad48b97d8158d7db31f9ada2ae5d58884c0fb7208b278b2dc9dbe6 +size 84366 diff --git a/docs/zh-CN/mcp.md b/docs/zh-CN/mcp.md index b7731d6..30ab23e 100644 --- a/docs/zh-CN/mcp.md +++ b/docs/zh-CN/mcp.md @@ -39,6 +39,43 @@ git-ai ai serve - `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）： @@ -119,37 +156,40 @@ git-ai ai agent install --agent trae 根据 `skill.yaml`，推荐的工作流程： -1. **绑定仓库** (`bind_repo`) - 确保仓库已绑定 -2. **确保索引新鲜** (`ensure_index`) - 必要时重建索引 -3. **定位符号** (`locate_symbols`) - 使用 `search_symbols` 精确查找 -4. **语义搜索** (`semantic_search`) - 自然语言描述搜索 -5. **浏览文件** (`browse_files`) - 使用 `list_files` 查找文件 -6. **AST 查询** (`ast_query`) - 递归/关系类查询 -7. **读取代码** (`read_code`) - 使用 `read_file` 读取关键片段 +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 必须遵守： -- **bind_repo_first**: 先绑定仓库再操作 -- **index_before_search**: 搜索无结果时先重建索引 -- **evidence_based_conclusion**: 结论必须有证据（文件+行号） -- **path_safety**: 禁止读取仓库外路径 -- **storage_cost_evaluation**: 评估存储成本 +- **explicit_path**: 每次调用必须显式传 `path` 参数 +- **check_index_first**: 符号搜索前必须检查索引 +- **understand_before_modify**: 修改前必须先理解实现 +- **use_dsr_for_history**: 追溯历史必须使用 DSR 工具 +- **respect_dsr_risk**: 重视 DSR 报告的 high 风险变更 禁止事项包括： -- 默认使用外部 embedding 服务 -- 直接提交 `.git-ai/lancedb/` 目录 -- 使用 `../` 读取外部文件 -- 假设索引是最新的而不检查 +- 假设符号位置而不搜索 +- 直接修改未读过的文件 +- 手动解析 git 历史 +- 在索引缺失时进行符号搜索 +- 省略 `path` 参数 ## DSR 与 MCP 的关系 -- MCP tools 主要覆盖“索引（.git-ai）构建与检索”，用于让 Agent 低成本定位证据 -- DSR 是“按提交的语义工件（.git-ai/dsr）”，用于语义历史/演化类查询与可重建缓存 +- **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 工具时应遵循： diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 99b8150..864becb 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -19,6 +19,11 @@ import { toPosixPath } from '../core/paths'; import { createLogger } from '../core/log'; import { checkIndex, resolveLangs } from '../core/indexCheck'; import { generateRepoMap, type FileRank } from '../core/repoMap'; +import { detectRepoGitContext } from '../core/dsr/gitContext'; +import { generateDsrForCommit } from '../core/dsr/generate'; +import { materializeDsrIndex } from '../core/dsr/indexMaterialize'; +import { symbolEvolution } from '../core/dsr/query'; +import { getDsrDirectoryState } from '../core/dsr/state'; export interface GitAIV2MCPServerOptions { disableAccessLog?: boolean; @@ -322,6 +327,56 @@ export class GitAIV2MCPServer { required: ['path', 'name'], }, }, + { + name: 'dsr_context', + description: 'Get repository Git context and DSR directory state. Risk: low (read-only).', + inputSchema: { + type: 'object', + properties: { + path: { type: 'string', description: 'Repository root path' }, + }, + required: ['path'], + }, + }, + { + name: 'dsr_generate', + description: 'Generate DSR (Deterministic Semantic Record) for a specific commit. Risk: medium (writes .git-ai/dsr).', + inputSchema: { + type: 'object', + properties: { + path: { type: 'string', description: 'Repository root path' }, + commit: { type: 'string', description: 'Commit hash or ref' }, + }, + required: ['path', 'commit'], + }, + }, + { + name: 'dsr_rebuild_index', + description: 'Rebuild DSR index from DSR files for faster queries. Risk: medium (writes .git-ai/dsr-index).', + inputSchema: { + type: 'object', + properties: { + path: { type: 'string', description: 'Repository root path' }, + }, + required: ['path'], + }, + }, + { + name: 'dsr_symbol_evolution', + description: 'Query symbol evolution history across commits using DSR. Risk: low (read-only).', + inputSchema: { + type: 'object', + properties: { + path: { type: 'string', description: 'Repository root path' }, + symbol: { type: 'string', description: 'Symbol name to query' }, + start: { type: 'string', description: 'Start commit (default: HEAD)' }, + all: { type: 'boolean', default: false, description: 'Traverse all refs instead of just HEAD' }, + limit: { type: 'number', default: 200, description: 'Max commits to traverse' }, + contains: { type: 'boolean', default: false, description: 'Match by substring instead of exact' }, + }, + required: ['path', 'symbol'], + }, + }, ], }; }); @@ -347,6 +402,67 @@ export class GitAIV2MCPServer { }; } + if (name === 'dsr_context') { + const repoRoot = await this.resolveRepoRoot(callPath); + const ctx = await detectRepoGitContext(repoRoot); + const state = await getDsrDirectoryState(ctx.repo_root); + return { + content: [{ type: 'text', text: JSON.stringify({ + ok: true, + commit_hash: ctx.head_commit, + repo_root: ctx.repo_root, + branch: ctx.branch, + detached: ctx.detached, + dsr_directory_state: state, + }, null, 2) }], + }; + } + + if (name === 'dsr_generate') { + const repoRoot = await this.resolveRepoRoot(callPath); + const commit = String((args as any).commit ?? 'HEAD'); + const res = await generateDsrForCommit(repoRoot, commit); + return { + content: [{ type: 'text', text: JSON.stringify({ + ok: true, + commit_hash: res.dsr.commit_hash, + file_path: res.file_path, + existed: res.existed, + counts: { + affected_symbols: res.dsr.affected_symbols.length, + ast_operations: res.dsr.ast_operations.length, + }, + semantic_change_type: res.dsr.semantic_change_type, + risk_level: res.dsr.risk_level, + }, null, 2) }], + }; + } + + if (name === 'dsr_rebuild_index') { + const repoRoot = await this.resolveRepoRoot(callPath); + const res = await materializeDsrIndex(repoRoot); + return { + content: [{ type: 'text', text: JSON.stringify({ repoRoot, ...res }, null, 2) }], + isError: !res.enabled, + }; + } + + if (name === 'dsr_symbol_evolution') { + const repoRoot = await this.resolveRepoRoot(callPath); + const symbol = String((args as any).symbol ?? ''); + const opts = { + start: (args as any).start ? String((args as any).start) : undefined, + all: Boolean((args as any).all ?? false), + limit: Number((args as any).limit ?? 200), + contains: Boolean((args as any).contains ?? false), + }; + const res = await symbolEvolution(repoRoot, symbol, opts); + return { + content: [{ type: 'text', text: JSON.stringify({ repoRoot, symbol, ...res }, null, 2) }], + isError: !res.ok, + }; + } + if (name === 'check_index') { const repoRoot = await this.resolveRepoRoot(callPath); const res = await checkIndex(repoRoot); diff --git a/templates/agents/common/rules/git-ai-mcp/RULE.md b/templates/agents/common/rules/git-ai-mcp/RULE.md index c8b3ef3..1ad7eba 100644 --- a/templates/agents/common/rules/git-ai-mcp/RULE.md +++ b/templates/agents/common/rules/git-ai-mcp/RULE.md @@ -1,15 +1,64 @@ -# git-ai-mcp +# git-ai-mcp Rule -Use `git-ai` as the single entry point for indexing and semantic queries. +Agent 使用 git-ai MCP 工具的行为约束。 -## Hard rules +## 必须遵守 -- Determine history and branches only from Git (never from semantic artifacts) -- Treat `.git-ai/dsr/.json` as immutable canonical artifacts -- Treat databases as rebuildable caches (derivable from DSR + Git) -- If DSR is missing for a commit needed by a query, report and stop (do not infer) +### explicit_path +- **级别**: error +- **规则**: 每次 MCP 工具调用必须显式传 `path` 参数。禁止依赖进程状态或工作目录隐式推断仓库位置。 -## Practical defaults +### check_index_first +- **级别**: error +- **规则**: 使用 `search_symbols`、`semantic_search`、`ast_graph_*` 前，必须先调用 `check_index` 确认索引就绪。索引不兼容时必须重建，禁止在索引缺失时进行符号搜索。 -- Prefer read-only operations unless explicitly asked to modify the repository -- For repository understanding, use MCP search tools first, then read code with line ranges +### understand_before_modify +- **级别**: error +- **规则**: 修改代码前必须先理解现有实现。流程：`search_symbols` 定位 → `read_file` 精读 → `ast_graph_callers` 确认影响范围 → 修改。禁止直接修改未读过的文件。 + +### use_dsr_for_history +- **级别**: warning +- **规则**: 追溯符号变更历史必须使用 `dsr_symbol_evolution`。禁止手动解析 git log 或 diff 来推断符号变更。 + +### repo_map_before_large_change +- **级别**: warning +- **规则**: 大型变更前必须使用 `repo_map` 确认影响范围。了解项目结构、关键文件、主要符号后再规划修改。 + +### respect_dsr_risk +- **级别**: warning +- **规则**: DSR 报告 `risk_level` 为 `high` 的变更必须谨慎对待。涉及 `delete`、`rename` 操作的变更需要额外审查。 + +## 推荐策略 + +- **优先语义搜索**: 理解功能意图时优先使用 `semantic_search`，精确定位时使用 `search_symbols`。 +- **使用调用链**: 复杂调用链路使用 `ast_graph_chain` 追踪，避免手动递归查找 callers/callees。 +- **按需生成 DSR**: 需要历史分析时，按需生成 DSR，避免一次性生成所有历史提交的 DSR。 +- **附带上下文**: 复杂查询可附带 `repo_map`，帮助建立全局上下文。 + +## 禁止事项 + +| 行为 | 原因 | +|------|------| +| 假设符号位置而不搜索 | 必须通过 `search_symbols` 或 `semantic_search` 确认符号位置 | +| 直接修改未读过的文件 | 必须先 `read_file` 理解实现，避免破坏性变更 | +| 手动解析 git 历史 | 必须使用 `dsr_symbol_evolution` 追溯符号变更 | +| 在索引缺失时进行符号搜索 | 索引是符号搜索的前提，缺失时必须重建 | +| 忽略 DSR 风险等级 | high 风险变更需要额外审查，不能盲目应用 | +| 省略 `path` 参数 | 每次调用必须显式传 path，保证原子性和可复现性 | + +## 工具使用约束 + +| 工具 | 使用时机 | 必传参数 | 前置检查 | +|------|----------|----------|----------| +| `repo_map` | 首次接触仓库、大型变更前 | `path` | - | +| `check_index` | 任何符号搜索前 | `path` | - | +| `rebuild_index` | 索引不兼容或缺失时 | `path` | - | +| `search_symbols` | 按名称查找符号 | `path`, `query` | `check_index` 通过 | +| `semantic_search` | 按语义查找代码 | `path`, `query` | `check_index` 通过 | +| `ast_graph_callers` | 查找调用者 | `path`, `name` | `check_index` 通过 | +| `ast_graph_callees` | 查找被调用者 | `path`, `name` | `check_index` 通过 | +| `ast_graph_chain` | 追踪调用链 | `path`, `name` | `check_index` 通过 | +| `dsr_context` | 了解仓库 Git 状态和 DSR 情况 | `path` | - | +| `dsr_generate` | 为特定提交生成 DSR | `path`, `commit` | - | +| `dsr_symbol_evolution` | 追溯符号变更历史 | `path`, `symbol` | 相关 DSR 已生成 | +| `read_file` | 精读代码 | `path`, `file` | - | diff --git a/templates/agents/common/rules/git-ai.yaml b/templates/agents/common/rules/git-ai.yaml index b630e58..83b1661 100644 --- a/templates/agents/common/rules/git-ai.yaml +++ b/templates/agents/common/rules/git-ai.yaml @@ -1,165 +1,141 @@ -name: trae-dsr +name: git-ai-mcp version: "2.0.0" description: | - Non-negotiable constraints for a Git-native, decentralized semantic indexing system. - Enforces DSR determinism/immutability, canonical-vs-cache boundaries, and Git DAG authority. - -global_invariants: - - "Git commit DAG is authoritative for history and branches." - - "DSR is per-commit, immutable, deterministic." - - "DSR files are canonical artifacts; databases are rebuildable caches." - - "Never infer Git topology from semantic data." - -precedence: - conflict_resolution_order: - - git - - dsr - - database - - heuristics - -canonical_artifacts: - dsr: - directory: ".git-ai/dsr" - file_pattern: ".json" - rules: - - "One commit → one DSR file." - - "DSR file must be immutable once generated." - -cli_entrypoints: - dsr: - - "git-ai ai dsr context --json" - - "git-ai ai dsr generate " - - "git-ai ai dsr rebuild-index" - - "git-ai ai dsr query symbol-evolution --json" - -dsr_schema: - required_fields: - - commit_hash - - affected_symbols - - ast_operations - - semantic_change_type - optional_fields: - - summary - - risk_level - forbidden_fields: - - parent_commits - - branch_names - - timestamps_beyond_commit_time - - merge_topology + Agent 使用 git-ai MCP 工具的行为约束。 + 确保 Agent 高效、安全、准确地帮助开发者理解和修改代码。 must_follow: - - id: git_is_authority + - id: explicit_path severity: error rule: | - Use Git commands to determine repo root, HEAD, branch, and history. - Never infer branches/parents/topology from semantic artifacts. + 每次 MCP 工具调用必须显式传 path 参数。 + 禁止依赖进程状态或工作目录隐式推断仓库位置。 - - id: do_not_parse_git_internals + - id: check_index_first severity: error rule: | - Do not parse .git internals manually. - Use git rev-parse / git show / git log / git diff. + 使用 search_symbols、semantic_search、ast_graph_* 前， + 必须先调用 check_index 确认索引就绪。 + 索引不兼容时必须重建，禁止在索引缺失时进行符号搜索。 - - id: per_commit_scope_only + - id: understand_before_modify severity: error rule: | - For a given commit, analyze only the snapshot defined by that commit. - Do not inspect future commits. + 修改代码前必须先理解现有实现。 + 流程：search_symbols 定位 → read_file 精读 → ast_graph_callers 确认影响范围 → 修改。 + 禁止直接修改未读过的文件。 - - id: dsr_determinism - severity: error + - id: use_dsr_for_history + severity: warning rule: | - DSR generation must be deterministic: same inputs produce identical DSR output. - No randomness, no time-based or environment-based variance. + 追溯符号变更历史必须使用 dsr_symbol_evolution。 + 禁止手动解析 git log 或 diff 来推断符号变更。 - - id: dsr_immutability - severity: error + - id: repo_map_before_large_change + severity: warning rule: | - Once written, a DSR file must not be modified. - If regeneration is necessary, treat it as a system error and stop. + 大型变更前必须使用 repo_map 确认影响范围。 + 了解项目结构、关键文件、主要符号后再规划修改。 - - id: cache_is_derivable - severity: error + - id: respect_dsr_risk + severity: warning rule: | - Databases and indexes are caches only. - Every semantic fact stored in any database must be derivable from DSR + Git. + DSR 报告 risk_level 为 high 的变更必须谨慎对待。 + 涉及 delete、rename 操作的变更需要额外审查。 - - id: read_only_query - severity: error +recommended: + - id: prefer_semantic_search rule: | - Query execution is read-only with respect to DSR. - DSR enriches commit nodes; it never defines DAG edges. + 理解功能意图时优先使用 semantic_search， + 精确定位时使用 search_symbols。 -if_data_missing: - - "Rebuild caches from DSR." - - "If DSR missing, report and stop (do NOT infer)." + - id: use_call_chain_for_complex_flow + rule: | + 复杂调用链路使用 ast_graph_chain 追踪， + 避免手动递归查找 callers/callees。 + + - id: incremental_dsr_generation + rule: | + 需要历史分析时，按需生成 DSR， + 避免一次性生成所有历史提交的 DSR。 + + - id: attach_repo_map_for_context + rule: | + 复杂查询可附带 repo_map， + 帮助建立全局上下文。 prohibited: - - action: "Inferring Git parents/branches/topology from semantic data" - reason: "Git DAG is authoritative; semantics may only enrich nodes" - - - action: "Writing semantic facts only into a database" - reason: "Databases must be derivable caches; DSR is canonical" - - - action: "Including parent commits or branch names in DSR" - reason: "DSR must not encode merge topology or branch structure" - - - action: "Mutating an existing DSR file" - reason: "DSR must be immutable once generated" - -phases: - phase_0: - name: "Context Discovery" - must_produce: - - commit_hash - - repo_root - - dsr_directory_state - tools: - - "git rev-parse" - - "git show" - - "git log" - - "filesystem inspection" - - phase_1: - name: "Commit Semantic Extraction" - tools: - - "git diff " - - "language parser → AST" - - "AST diff engine" - - "semantic rules engine" - must_produce: - - ast_diff - - symbol_level_operations - - phase_2: - name: "DSR Generation" - output_path: ".git-ai/dsr/.json" - - phase_3: - name: "Cache / Index Materialization" - tools: - - "SQLite / CozoDB" - - "LanceDB" - - phase_4: - name: "Versioning & Distribution" - tools: - - "Git LFS" - - "pre-commit / pre-push hooks" - must_hold: - - "DSR files are Git-visible." - - "No central service required." - - phase_5: - name: "Clone / Pull / Checkout Handling" - rules: - - "Never persist checkout-specific state into DSR." - - "Git DAG traversal always comes first." - - phase_6: - name: "Query Execution" - supported_queries: - - semantic_blame - - semantic_diff - - symbol_evolution - - semantic_search + - action: "假设符号位置而不搜索" + reason: "必须通过 search_symbols 或 semantic_search 确认符号位置" + + - action: "直接修改未读过的文件" + reason: "必须先 read_file 理解实现，避免破坏性变更" + + - action: "手动解析 git 历史" + reason: "必须使用 dsr_symbol_evolution 追溯符号变更" + + - action: "在索引缺失时进行符号搜索" + reason: "索引是符号搜索的前提，缺失时必须重建" + + - action: "忽略 DSR 风险等级" + reason: "high 风险变更需要额外审查，不能盲目应用" + + - action: "省略 path 参数" + reason: "每次调用必须显式传 path，保证原子性和可复现性" + +tool_usage_constraints: + repo_map: + when: "首次接触仓库、大型变更前" + must_pass: ["path"] + + check_index: + when: "任何符号搜索前" + must_pass: ["path"] + + rebuild_index: + when: "索引不兼容或缺失时" + must_pass: ["path"] + note: "可能耗时较长，大型仓库谨慎使用" + + search_symbols: + when: "按名称查找符号" + must_pass: ["path", "query"] + precheck: "check_index 必须通过" + + semantic_search: + when: "按语义查找代码" + must_pass: ["path", "query"] + precheck: "check_index 必须通过" + + ast_graph_callers: + when: "查找调用者" + must_pass: ["path", "name"] + precheck: "check_index 必须通过" + + ast_graph_callees: + when: "查找被调用者" + must_pass: ["path", "name"] + precheck: "check_index 必须通过" + + ast_graph_chain: + when: "追踪调用链" + must_pass: ["path", "name"] + precheck: "check_index 必须通过" + + dsr_context: + when: "了解仓库 Git 状态和 DSR 情况" + must_pass: ["path"] + + dsr_generate: + when: "为特定提交生成 DSR" + must_pass: ["path", "commit"] + + dsr_symbol_evolution: + when: "追溯符号变更历史" + must_pass: ["path", "symbol"] + precheck: "相关提交的 DSR 必须已生成" + + read_file: + when: "精读代码" + must_pass: ["path", "file"] + note: "建议结合 start_line/end_line 限制范围" diff --git a/templates/agents/common/skills/git-ai-mcp/SKILL.md b/templates/agents/common/skills/git-ai-mcp/SKILL.md index 22b98aa..29c2307 100644 --- a/templates/agents/common/skills/git-ai-mcp/SKILL.md +++ b/templates/agents/common/skills/git-ai-mcp/SKILL.md @@ -1,25 +1,135 @@ -# git-ai-mcp +# git-ai-mcp Skill -This skill helps an agent use `git-ai` safely for: +指导 Agent 使用 git-ai MCP 工具高效理解和操作代码库。 -- Repository indexing/search via MCP (`git-ai ai serve`) -- Per-commit semantics via DSR (Deterministic Semantic Record) +## 目标用户 -## Key invariants +使用 Claude Desktop、Trae 等支持 MCP 的本地 Code Agent 的开发者。 -- Git commit DAG is authoritative for history/branches -- DSR is per-commit, immutable, deterministic -- DSR files are canonical artifacts; databases are rebuildable caches -- Never infer Git topology from semantic data +## 核心能力 -## Recommended workflow +1. **仓库全局理解** - 通过 `repo_map` 快速获取项目结构和关键文件概览 +2. **符号检索** - 使用 `search_symbols` 和 `semantic_search` 定位代码 +3. **代码关系分析** - 通过 `ast_graph_callers/callees/chain` 理解调用关系 +4. **变更历史追溯** - 使用 `dsr_symbol_evolution` 追踪符号演变 +5. **代码精读** - 使用 `read_file` 深入理解关键代码片段 +6. **索引管理** - 按需重建索引，确保检索准确性 -1. (Optional) Build repository index (checkout-local cache): - - `git-ai ai index --overwrite` -2. Start MCP server for symbol/semantic/graph tools: - - `git-ai ai serve` -3. For history/evolution questions, rely on DSR (commit-addressable artifacts): - - Inspect: `git-ai ai dsr context --json` - - Generate for one commit: `git-ai ai dsr generate ` - - Rebuild cache index: `git-ai ai dsr rebuild-index` - - Query (read-only, Git DAG first): `git-ai ai dsr query symbol-evolution --json` +## 推荐工作流 + +### 1. 首次接触仓库 + +获取全局视图，了解项目结构： + +```js +repo_map({ path: "/ABS/PATH/TO/REPO", max_files: 20, max_symbols: 5 }) +``` + +### 2. 检查索引状态 + +确保索引就绪，否则重建： + +```js +check_index({ path: "/ABS/PATH/TO/REPO" }) +// 如果不兼容，重建： +rebuild_index({ path: "/ABS/PATH/TO/REPO" }) +``` + +### 3. 定位目标代码 + +按名称查找： + +```js +search_symbols({ path: "/ABS/PATH/TO/REPO", query: "handleRequest", mode: "substring", limit: 20 }) +``` + +按语义查找： + +```js +semantic_search({ path: "/ABS/PATH/TO/REPO", query: "用户认证逻辑在哪里", topk: 10 }) +``` + +### 4. 理解代码关系 + +查找调用者： + +```js +ast_graph_callers({ path: "/ABS/PATH/TO/REPO", name: "handleRequest", limit: 50 }) +``` + +查找被调用者： + +```js +ast_graph_callees({ path: "/ABS/PATH/TO/REPO", name: "handleRequest", limit: 50 }) +``` + +追踪调用链： + +```js +ast_graph_chain({ path: "/ABS/PATH/TO/REPO", name: "handleRequest", direction: "upstream", max_depth: 3 }) +``` + +### 5. 追溯变更历史 + +查看符号的历史变更： + +```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 }) +``` + +### 6. 精读代码 + +```js +read_file({ path: "/ABS/PATH/TO/REPO", file: "src/auth.ts", start_line: 1, end_line: 100 }) +``` + +### 7. 提供建议 + +基于完整的代码理解，提供修改建议或生成代码。 + +## 工具选择指南 + +| 场景 | 工具 | 关键参数 | +|------|------|----------| +| 了解项目结构 | `repo_map` | `path`, `max_files`, `max_symbols` | +| 按名称查找符号 | `search_symbols` | `path`, `query`, `mode`, `limit` | +| 按语义查找代码 | `semantic_search` | `path`, `query`, `topk` | +| 查找调用者 | `ast_graph_callers` | `path`, `name`, `limit` | +| 查找被调用者 | `ast_graph_callees` | `path`, `name`, `limit` | +| 追踪调用链 | `ast_graph_chain` | `path`, `name`, `direction`, `max_depth` | +| 查看符号历史 | `dsr_symbol_evolution` | `path`, `symbol`, `limit` | +| 生成 DSR | `dsr_generate` | `path`, `commit` | +| 读取代码 | `read_file` | `path`, `file`, `start_line`, `end_line` | + +## 最佳实践 + +1. **每次调用必须显式传 `path` 参数**，保证调用原子性 +2. **优先使用高层语义工具**（symbol search）而非低层文件遍历 +3. **修改代码前必须先理解现有实现**，避免破坏性变更 +4. **使用 DSR 工具理解历史变更**，而非手动 git log +5. **大型变更前先 `repo_map` 确认影响范围** +6. **索引不兼容时及时重建**，确保检索准确性 + +## 常见陷阱 + +- ❌ 不要假设符号位置，必须通过 search 确认 +- ❌ 不要直接修改未读过的文件 +- ❌ 不要手动解析 git 历史，使用 DSR 工具 +- ❌ 不要在索引缺失时进行符号搜索 +- ❌ 不要忽略 DSR 的风险等级提示 + +## 触发模式 + +当用户说以下话时，使用对应工具： + +- "帮我理解这个项目" / "项目结构是什么" → `repo_map` +- "查找 XX 函数" / "搜索 XX 方法" → `search_symbols` +- "XX 在哪里实现" / "XX 怎么调用" → `semantic_search` + `ast_graph_callers` +- "XX 的变更历史" / "XX 什么时候修改" → `dsr_symbol_evolution` +- "重构 XX" / "修改 XX" → 先 `callers/callees/chain` 确认影响范围 diff --git a/templates/agents/common/skills/git-ai/skill.yaml b/templates/agents/common/skills/git-ai/skill.yaml index d3c6cb8..5c46ff3 100644 --- a/templates/agents/common/skills/git-ai/skill.yaml +++ b/templates/agents/common/skills/git-ai/skill.yaml @@ -1,168 +1,124 @@ -name: trae-dsr +name: git-ai-mcp version: "2.0.0" +description: | + 指导 Agent 使用 git-ai MCP 工具高效理解和操作代码库。 + 适用于 Claude Desktop、Trae 等支持 MCP 的本地 Code Agent。 + role: | - You are Trae, an autonomous code agent implementing a Git-native, decentralized semantic indexing system. - -global_invariants: - - "Git commit DAG is authoritative for history and branches." - - "DSR is per-commit, immutable, deterministic." - - "DSR files are canonical artifacts; databases are rebuildable caches." - - "Never infer Git topology from semantic data." - -fail_safe_rules: - conflict_precedence: - - git - - dsr - - database - - heuristics - missing_data_behavior: - - "Rebuild caches from DSR." - - "If DSR missing, report and stop (do NOT infer)." - -design_philosophy: | - Semantic understanding is a first-class, commit-addressable artifact, - but Git remains the sole authority over history. - -cli_entrypoints: - dsr: - - "git-ai ai dsr context --json" - - "git-ai ai dsr generate " - - "git-ai ai dsr rebuild-index" - - "git-ai ai dsr query symbol-evolution --json" + 你是开发者的智能助手，专注于帮助开发者快速理解代码库结构、 + 定位关键代码、分析代码关系、追溯变更历史，并提供精准的代码修改建议。 + +core_capabilities: + - 仓库全局理解：通过 repo_map 快速获取项目结构和关键文件概览 + - 符号检索：使用 search_symbols 和 semantic_search 定位代码 + - 代码关系分析：通过 ast_graph_callers/callees/chain 理解调用关系 + - 变更历史追溯：使用 dsr_symbol_evolution 追踪符号演变 + - 代码精读：使用 read_file 深入理解关键代码片段 + - 索引管理：按需重建索引，确保检索准确性 + +recommended_workflow: + - step: 1 + name: "首次接触仓库" + action: | + 调用 repo_map({ path, max_files: 20, max_symbols: 5 }) 获取全局视图。 + 了解项目结构、关键文件、主要符号，为后续分析建立上下文。 + + - step: 2 + name: "检查索引状态" + action: | + 调用 check_index({ path }) 检查索引是否就绪。 + 如果索引不兼容或缺失，调用 rebuild_index({ path }) 重建。 + + - step: 3 + name: "定位目标代码" + action: | + 使用 search_symbols({ path, query, mode: 'substring', limit: 20 }) + 或 semantic_search({ path, query, topk: 10 }) 定位相关代码。 + 优先使用语义搜索理解功能意图，使用符号搜索精确定位。 + + - step: 4 + name: "理解代码关系" + action: | + 找到关键符号后，使用 ast_graph_callers/callees 分析调用关系。 + 对于复杂链路，使用 ast_graph_chain 追踪上下游调用链。 + + - step: 5 + name: "追溯变更历史" + action: | + 使用 dsr_symbol_evolution({ path, symbol, limit: 50 }) + 了解符号的历史变更，包括修改类型、风险等级、操作详情。 + + - step: 6 + name: "精读代码" + action: | + 使用 read_file({ path, file, start_line, end_line }) + 精读关键代码片段，理解实现细节。 + + - step: 7 + name: "提供建议" + action: | + 基于完整的代码理解，提供修改建议或生成代码。 + +best_practices: + - "每次工具调用必须显式传 path 参数，保证调用原子性" + - "优先使用高层语义工具（symbol search）而非低层文件遍历" + - "修改代码前必须先理解现有实现，避免破坏性变更" + - "使用 DSR 工具理解历史变更，而非手动 git log" + - "大型变更前先 repo_map 确认影响范围" + - "索引不兼容时及时重建，确保检索准确性" + +tool_selection_guide: + - scenario: "了解项目结构" + tool: repo_map + params: { path, max_files: 20, max_symbols: 5 } + + - scenario: "按名称查找符号" + tool: search_symbols + params: { path, query, mode: 'substring|prefix|wildcard', limit: 50 } + + - scenario: "按语义查找代码" + tool: semantic_search + params: { path, query, topk: 10 } + + - scenario: "查找调用者" + tool: ast_graph_callers + params: { path, name, limit: 50 } + + - scenario: "查找被调用者" + tool: ast_graph_callees + params: { path, name, limit: 50 } + + - scenario: "追踪调用链" + tool: ast_graph_chain + params: { path, name, direction: 'upstream|downstream', max_depth: 3 } + + - scenario: "查看符号历史" + tool: dsr_symbol_evolution + params: { path, symbol, limit: 50, contains: false } + + - scenario: "生成 DSR" + tool: dsr_generate + params: { path, commit: 'HEAD' } + + - scenario: "读取代码" + tool: read_file + params: { path, file, start_line: 1, end_line: 200 } + +common_pitfalls: + - "不要假设符号位置，必须通过 search 确认" + - "不要直接修改未读过的文件" + - "不要手动解析 git 历史，使用 DSR 工具" + - "不要在索引缺失时进行符号搜索" + - "不要忽略 DSR 的风险等级提示" triggers: - - pattern: "semantic blame|semantic diff|symbol evolution|semantic search" - - pattern: "generate dsr|dsr generation|deterministic semantic record" - - pattern: "index materialization|rebuild cache|materialize index" - - pattern: "checkout handling|clone handling|pull handling" - -supported_queries: - - semantic_blame - - semantic_diff - - symbol_evolution - - semantic_search - -phases: - - phase: 0 - name: "Context Discovery" - task: - - "Identify repository root." - - "Detect current HEAD commit and branch via Git (not via files)." - - "Detect presence of .git-ai and existing DSR files." - tools: - - "git rev-parse" - - "git show" - - "git log" - - "filesystem inspection" - artifacts: - - commit_hash - - repo_root - - dsr_directory_state - rules: - - "Do NOT assume linear history." - - "Do NOT parse Git internals manually." - - "Never infer Git topology from semantic data." - - - phase: 1 - name: "Commit Semantic Extraction" - task: - - "Given a specific commit, derive its semantic meaning." - tools: - - "git diff " - - "language parser → AST" - - "AST diff engine" - - "semantic rules engine" - artifacts: - - ast_diff - - symbol_level_operations - rules: - - "Only analyze the snapshot defined by the commit." - - "Do NOT inspect future commits." - - "Determinism required: same input → same output." - - "If the commit has multiple parents, do not infer merge topology from semantics." - - - phase: 2 - name: "DSR Generation (Canonical)" - task: - - "Generate a Deterministic Semantic Record for exactly one commit." - tools: - - "JSON / MsgPack serializer" - - "content hashing (optional)" - artifact_path: ".git-ai/dsr/.json" - required_fields: - - commit_hash - - affected_symbols - - ast_operations - - semantic_change_type - - summary - - risk_level - forbidden_fields: - - parent_commits - - branch_names - - timestamps_beyond_commit_time - - merge_topology - rules: - - "One commit → one DSR file." - - "File must be immutable once generated." - - - phase: 3 - name: "Cache / Index Materialization" - task: - - "Update local performance-oriented stores." - tools: - - "SQLite / CozoDB (AST graph, symbol DAG)" - - "LanceDB (embeddings)" - artifacts: - - ast_db - - symbol_graph_db - - embedding_index - rules: - - "Databases must be derivable from DSR + Git." - - "No semantic fact may exist only inside a database." - - - phase: 4 - name: "Versioning & Distribution" - task: - - "Ensure semantic artifacts are distributed via Git." - tools: - - "Git LFS" - - "pre-commit / pre-push hooks" - artifacts: - - lfs_tracked_dsr_files - - compressed_cache_snapshots_optional - rules: - - "DSR files must be Git-visible." - - "Distribution must not require a central service." - - - phase: 5 - name: "Clone / Pull / Checkout Handling" - task: - - "Handle repository state changes safely." - tools: - - "git clone" - - "git pull" - - "git checkout" - - "filesystem checks" - behavior: - on_clone: - - "Fetch DSR files via Git LFS." - - "If caches missing → rebuild from DSR." - on_checkout: - - "Query Git DAG for history." - - "Attach DSR data to commits dynamically." - rules: - - "Never persist checkout-specific state into DSR." - - "Git DAG traversal always comes first." - - - phase: 6 - name: "Query Execution (Read-Only)" - task: - - "Answer semantic queries." - tools: - - "Git DAG traversal" - - "DSR filtering" - - "AST / symbol DAG aggregation" - - "embedding similarity (optional)" - rules: - - "History traversal must start from Git DAG." - - "DSR only enriches nodes; never defines edges." + - pattern: "帮我理解这个项目|项目结构是什么" + action: "使用 repo_map 获取全局视图" + - pattern: "查找.*函数|搜索.*方法" + action: "使用 search_symbols 定位符号" + - pattern: ".*在哪里实现|.*怎么调用" + action: "使用 semantic_search + ast_graph_callers 定位并分析" + - pattern: ".*的变更历史|.*什么时候修改" + action: "使用 dsr_symbol_evolution 追溯历史" + - pattern: "重构.*|修改.*" + action: "先使用 callers/callees/chain 确认影响范围，再修改"