Refactor/cli commands architecture

AGENTS.md

@@ -1,8 +1,8 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-01-31 23:03
-**Commit:** 680e8f2
-**Branch:** copilot/add-index-commit-id-feature
+**Generated:** 2026-02-02 01:45
+**Commit:** bd3baf8
+**Branch:** refactor/cli-commands-architecture
 
 ## OVERVIEW
 git-ai CLI + MCP server. TypeScript implementation for AI-powered Git operations with semantic search, DSR (Deterministic Semantic Record), and graph-based code analysis. Indices stored in `.git-ai/`.
@@ -11,7 +11,14 @@ git-ai CLI + MCP server. TypeScript implementation for AI-powered Git operations
 ```
 git-ai-cli-v2/
 ├── src/
-│   ├── commands/     # CLI subcommands (ai, graph, query, etc.)
+│   ├── cli/          # CLI command architecture (NEW: registry + handlers + schemas)
+│   │   ├── types.ts        # Core types, executeHandler
+│   │   ├── registry.ts     # Handler registry (24 commands)
+│   │   ├── helpers.ts      # Shared utilities
+│   │   ├── schemas/        # Zod validation schemas
+│   │   ├── handlers/       # Business logic handlers
+│   │   └── commands/       # Commander.js wrappers
+│   ├── commands/     # Command aggregator (ai.ts only)
 │   ├── core/         # Indexing, DSR, graph, storage, parsers
 │   └── mcp/          # MCP server implementation
 ├── test/             # Node test runner tests
@@ -22,7 +29,11 @@ git-ai-cli-v2/
 ## WHERE TO LOOK
 | Task | Location |
 |------|----------|
-| CLI commands | `src/commands/*.ts` |
+| CLI commands | `src/cli/commands/*.ts` (new architecture) |
+| CLI handlers | `src/cli/handlers/*.ts` (business logic) |
+| CLI schemas | `src/cli/schemas/*.ts` (Zod validation) |
+| Handler registry | `src/cli/registry.ts` (all 24 commands) |
+| Command aggregator | `src/commands/ai.ts` (entry point) |
 | Indexing logic | `src/core/indexer.ts`, `src/core/indexerIncremental.ts` |
 | DSR (commit records) | `src/core/dsr/`, `src/core/dsr.ts` |
 | Graph queries | `src/core/cozo.ts`, `src/core/astGraph.ts` |

README.md

@@ -9,7 +9,7 @@
 [![license](https://img.shields.io/github/license/mars167/git-ai-cli)](./LICENSE)
 [![npm version](https://img.shields.io/npm/v/@mars167/git-ai)](https://www.npmjs.com/package/@mars167/git-ai)
 [![npm downloads](https://img.shields.io/npm/dm/@mars167/git-ai)](https://www.npmjs.com/package/@mars167/git-ai)
-[![Agent Skill](https://img.shields.io/badge/Agent_Skill-git--ai--mcp-blue)](https://skills.sh)
+[![Agent Skill](https://img.shields.io/badge/Agent_Skill-git--ai--code--search-blue)](https://skills.sh)
 
 [🇨🇳 简体中文](./README.zh-CN.md) | **English**
 
@@ -22,7 +22,7 @@
 **For AI Agents (Claude Code, Cursor, Windsurf, etc.)**
 
 ```bash
-npx skills add mars167/git-ai-cli/skills/git-ai-mcp
+npx skills add mars167/git-ai-cli/skills/git-ai-code-search
 ```
 
 **For CLI Usage**
@@ -286,15 +286,63 @@ That's it! 3 steps to get started, immediately begin deep understanding of your
 
 ---
 
+## 🛠️ Troubleshooting
+
+### Windows Installation Issues
+
+git-ai uses [CozoDB](https://github.com/cozodb/cozo) for AST graph queries. On Windows, if you encounter installation errors related to `cozo-node`, try these solutions:
+
+**Option 1: Use Gitee Mirror (Recommended for users in China)**
+
+```bash
+npm install -g @mars167/git-ai --cozo_node_prebuilt_binary_host_mirror=https://gitee.com/cozodb/cozo-lib-nodejs/releases/download/
+```
+
+**Option 2: Configure npm proxy**
+
+If you're behind a corporate firewall or proxy:
+
+```bash
+npm config set proxy http://your-proxy:port
+npm config set https-proxy http://your-proxy:port
+npm install -g @mars167/git-ai
+```
+
+**Option 3: Manual binary download**
+
+1. Download the Windows binary from [cozo-lib-nodejs releases](https://github.com/cozodb/cozo-lib-nodejs/releases)
+2. Look for `6-win32-x64.tar.gz` (for 64-bit Windows)
+3. Extract to `node_modules/cozo-node/native/6/`
+
+**Verify installation:**
+
+```bash
+git-ai ai status --path .
+```
+
+If you see graph-related features working, installation was successful.
+
+### Other Native Dependencies
+
+git-ai also uses these native packages that may require similar troubleshooting:
+- `onnxruntime-node` - For semantic embeddings
+- `tree-sitter` - For code parsing
+- `@lancedb/lancedb` - For vector database
+
+Most issues are resolved by ensuring a stable network connection or using a mirror.
+
+---
+
 ## 🤖 AI Agent Integration
 
 git-ai provides a standard MCP Server that seamlessly integrates with:
 
 - **Claude Desktop**: The most popular local AI programming assistant
+- **Cursor**: AI-powered code editor
 - **Trae**: Powerful AI-driven IDE
 - **Continue.dev**: VS Code AI plugin
 
-### Claude Desktop Configuration Example
+### Single Agent (stdio mode - default)
 
 Add to `~/.claude/claude_desktop_config.json`:
 
@@ -309,6 +357,23 @@ Add to `~/.claude/claude_desktop_config.json`:
 }
 ```
 
+### Multiple Agents (HTTP mode)
+
+When you need multiple AI agents to connect simultaneously (e.g., Claude Code + Cursor):
+
+```bash
+# Start HTTP server (supports multiple clients)
+git-ai ai serve --http --port 3000
+```
+
+Then configure each agent to connect to `http://localhost:3000/mcp`.
+
+**HTTP mode features:**
+- Multiple concurrent sessions
+- Health check endpoint: `http://localhost:3000/health`
+- Session management with automatic cleanup
+- Optional stateless mode for load-balanced setups: `--stateless`
+
 Then restart Claude Desktop and start conversing:
 
 > "Help me analyze this project's architecture, find all payment-related code"
@@ -319,8 +384,8 @@ Claude will automatically invoke git-ai tools to provide deep analysis.
 
 We provide carefully designed Agent templates to help AI use git-ai better:
 
-- [Skill Template](./templates/agents/common/skills/git-ai-mcp/SKILL.md): Guides Agents on how to use tools
-- [Rule Template](./templates/agents/common/rules/git-ai-mcp/RULE.md): Constrains Agent behavior
+- [Skill Template](./templates/agents/common/skills/git-ai-code-search/SKILL.md): Guides Agents on how to use tools
+- [Rule Template](./templates/agents/common/rules/git-ai-code-search/RULE.md): Constrains Agent behavior
 
 Skills/Rules docs (Markdown/YAML) are indexed as part of semantic search, so agents can retrieve MCP guidance via `semantic_search`.
 

README.zh-CN.md

@@ -18,7 +18,7 @@
 **AI Agent 技能安装 (Claude Code, Cursor, Windsurf 等)**
 
 ```bash
-npx skills add mars167/git-ai-cli/skills/git-ai-mcp
+npx skills add mars167/git-ai-cli/skills/git-ai-code-search
 ```
 
 **CLI 工具安装**
@@ -283,15 +283,63 @@ git-ai ai graph callers authenticateUser
 
 ---
 
+## 🛠️ 故障排除
+
+### Windows 安装问题
+
+git-ai 使用 [CozoDB](https://github.com/cozodb/cozo) 来实现 AST 图查询功能。在 Windows 上，如果遇到 `cozo-node` 相关的安装错误，可以尝试以下解决方案：
+
+**方案一：使用 Gitee 镜像（推荐国内用户使用）**
+
+```bash
+npm install -g @mars167/git-ai --cozo_node_prebuilt_binary_host_mirror=https://gitee.com/cozodb/cozo-lib-nodejs/releases/download/
+```
+
+**方案二：配置 npm 代理**
+
+如果你在公司防火墙或代理后面：
+
+```bash
+npm config set proxy http://your-proxy:port
+npm config set https-proxy http://your-proxy:port
+npm install -g @mars167/git-ai
+```
+
+**方案三：手动下载二进制文件**
+
+1. 从 [cozo-lib-nodejs releases](https://github.com/cozodb/cozo-lib-nodejs/releases) 下载 Windows 二进制文件
+2. 找到 `6-win32-x64.tar.gz`（64 位 Windows）
+3. 解压到 `node_modules/cozo-node/native/6/` 目录
+
+**验证安装：**
+
+```bash
+git-ai ai status --path .
+```
+
+如果看到 graph 相关功能正常工作，说明安装成功。
+
+### 其他原生依赖
+
+git-ai 还使用了以下原生包，可能需要类似的故障排除：
+- `onnxruntime-node` - 用于语义向量生成
+- `tree-sitter` - 用于代码解析
+- `@lancedb/lancedb` - 用于向量数据库
+
+大多数问题可以通过确保稳定的网络连接或使用镜像来解决。
+
+---
+
 ## 🤖 AI Agent 集成
 
 git-ai 提供标准的 MCP Server，可与以下 AI Agent 无缝集成：
 
 - **Claude Desktop**：最流行的本地 AI 编程助手
+- **Cursor**：AI 驱动的代码编辑器
 - **Trae**：强大的 AI 驱动 IDE
 - **Continue.dev**：VS Code AI 插件
 
-### Claude Desktop 配置示例
+### 单客户端模式（stdio，默认）
 
 在 `~/.claude/claude_desktop_config.json` 中添加：
 
@@ -306,6 +354,23 @@ git-ai 提供标准的 MCP Server，可与以下 AI Agent 无缝集成：
 }
 ```
 
+### 多客户端模式（HTTP）
+
+当你需要多个 AI Agent 同时连接时（如同时使用 Claude Code 和 Cursor）：
+
+```bash
+# 启动 HTTP 服务（支持多客户端）
+git-ai ai serve --http --port 3000
+```
+
+然后配置每个 Agent 连接到 `http://localhost:3000/mcp`。
+
+**HTTP 模式特性：**
+- 支持多个并发会话
+- 健康检查端点：`http://localhost:3000/health`
+- 自动管理会话生命周期
+- 可选无状态模式，用于负载均衡场景：`--stateless`
+
 然后重启 Claude Desktop，即可开始对话：
 
 > "帮我分析这个项目的架构，找出所有与支付相关的代码"
@@ -316,8 +381,8 @@ Claude 会自动调用 git-ai 的工具，为你提供深入的分析。
 
 我们提供了精心设计的 Agent 模版，帮助 AI 更好地使用 git-ai：
 
-- [Skill 模版](./templates/agents/common/skills/git-ai-mcp/SKILL.md)：指导 Agent 如何使用工具
-- [Rule 模版](./templates/agents/common/rules/git-ai-mcp/RULE.md)：约束 Agent 的行为
+- [Skill 模版](./templates/agents/common/skills/git-ai-code-search/SKILL.md)：指导 Agent 如何使用工具
+- [Rule 模版](./templates/agents/common/rules/git-ai-code-search/RULE.md)：约束 Agent 的行为
 
 Skills/Rules 文档（Markdown/YAML）会被纳入语义索引，便于通过 `semantic_search` 检索 MCP 指南。