内容
<p align="center">
<img src="./github-githits.png" alt="GitHits" width="100%" />
</p>
<h1 align="center">GitHits CLI</h1>
<p align="center">
为 AI 编程代理提供版本感知的开源上下文。
</p>
<p align="center">
<a href="https://www.npmjs.com/package/githits"><img alt="npm 版本" src="https://img.shields.io/npm/v/githits.svg"></a>
<a href="https://www.npmjs.com/package/githits"><img alt="npm 下载量" src="https://img.shields.io/npm/dm/githits.svg"></a>
<a href="https://github.com/githits-com/githits-cli/actions/workflows/main.yml"><img alt="Main" src="https://github.com/githits-com/githits-cli/actions/workflows/main.yml/badge.svg"></a>
<a href="https://github.com/githits-com/githits-cli/blob/main/LICENSE"><img alt="许可证：Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
<a href="https://www.npmjs.com/package/githits"><img alt="Node" src="https://img.shields.io/node/v/githits.svg"></a>
<a href="https://modelcontextprotocol.io/"><img alt="MCP" src="https://img.shields.io/badge/MCP-enabled-5C4EE5"></a>
</p>
<p align="center">
<a href="https://githits.com">官网</a> ·
<a href="https://docs.githits.com">文档</a> ·
<a href="https://github.com/githits-com/githits-cli/issues">问题</a>
</p>
GitHits 将 AI 编程代理连接到公共的开源代码、软件包文档、元数据、漏洞、变更日志、依赖关系图、升级证据和实际实现示例，当本地仓库上下文不够用时。
CLI 运行一个本地的 [MCP](https://modelcontextprotocol.io/) 服务器，由您的编程工具按需启动。代理可以搜索索引的软件包和仓库源，读取确切的文件和文档页面，检查软件包健康状况，比较依赖关系升级，并从实际的开源项目中找到源引用的示例。
## 快速开始
```sh
npx githits@latest init
```
`init` 会为您登录，检测支持的编程工具，并为所选工具配置本地 GitHits MCP 服务器。
自动设置目前支持 Claude Code、Cursor、Windsurf、VS Code / Copilot、Cline、Claude Desktop、Codex CLI、Pi、Gemini CLI、Google Antigravity、OpenCode 和 Hermes Agent。
设置完成后，打开您的编程代理并正常工作。许多代理在需要源代码支持的上下文时会调用 GitHits。如果您的代理开始猜测，请直接提示它：
```text
使用 GitHits 代码导航检查 npm:express。查找中间件错误的处理方式，读取相关源代码，并解释修复方法，然后再编辑代码。
```
## GitHits 新增功能
GitHits 设计用于解决代理的模型知识和本地仓库访问无法满足需求的场景：
| 功能 | MCP 工具 | CLI 命令 |
| --- | --- | --- |
| 代码示例 | `get_example`, `search_language` | `githits example`, `githits languages` |
| 代码导航 | `search`, `search_status`, `code_files`, `code_read`, `code_grep` | `githits search`, `githits search-status`, `githits code ...` |
| 文档访问 | `docs_list`, `docs_read` | `githits docs ...` |
| 软件包检查 | `pkg_info`, `pkg_vulns`, `pkg_deps`, `pkg_changelog`, `pkg_upgrade_review` | `githits pkg ...` |
| 反馈 | `feedback` | `githits feedback` |
在以下情况下使用 GitHits：
- 在更改代码之前，验证依赖关系的实际行为
- 检查特定软件包版本的源代码、测试、符号或文档
- 调试指向第三方代码的堆栈跟踪
- 审查软件包健康状况、许可证、漏洞、依赖关系和变更日志
- 使用实际证据比较依赖关系升级
- 从实际仓库、问题、讨论和拉取请求中借鉴实现模式
## 示例
在开源中查找先前技术：
```sh
npx githits@latest example "Python 中的 HTTP 重试和指数退避"
```
搜索索引代码、文档和依赖关系的符号：
```sh
npx githits@latest search "router middleware" --in npm:express
npx githits@latest search '"body parser" OR multer' --in npm:express --source docs
npx githits@latest search "debounce" --in npm:lodash --source symbol
```
在不克隆的情况下读取和 grep 依赖关系的源代码：
```sh
npx githits@latest code files npm:express lib
npx githits@latest code read npm:express lib/router/index.js --lines 120-200
npx githits@latest code grep npm:express "router.use" lib --regex
```
检查软件包健康状况和升级证据：
```sh
npx githits@latest pkg info npm:express
npx githits@latest pkg vulns npm:lodash@4.17.20 --severity high
npx githits@latest pkg deps npm:express@4.18.2 --depth 2
npx githits@latest pkg changelog npm:express --from 4.18.2 --to 5.2.1
npx githits@latest pkg upgrade-review npm:zod@4.3.6 --to 4.4.3
```
浏览和阅读软件包文档：
```sh
npx githits@latest docs list npm:express
npx githits@latest docs read <page-id> --lines 20-80
```
## 支持的源
GitHits 支持以下软件包和仓库目标：
- 软件包规格：`npm:react`、`npm:react@18.2.0`、`pypi:requests`、`crates:serde`
- GitHub 仓库：`https://github.com/expressjs/express`、`github:expressjs/express#main`
软件包检查支持 npm、PyPI、Hex、Crates、NuGet、Maven、Packagist、RubyGems、Go、Swift、vcpkg 和 Zig。vcpkg 和 Zig 无可用性数据；依赖图支持因注册表而异。
## 许可证过滤
代码示例搜索支持许可证过滤：
- `strict` 是默认的，会过滤具有 copyleft 或未声明许可证的仓库
- `custom` 使用您在 [githits.com](https://githits.com) 上配置的帐户阻止列表
- `yolo` 禁用许可证过滤
```sh
npx githits@latest example "async file reading" --lang python --license strict
```
## 身份验证
正常的本地设置由以下命令处理：
```sh
npx githits@latest init
```
手动登录：
```sh
npx githits@latest login
```
推荐在本地开发中使用浏览器 OAuth。凭证默认存储在系统钥匙串中，并自动刷新。实用标志：
- `--no-browser` 为 SSH、容器或无头会话打印登录 URL
- `--force` 重新认证，即使您已经登录
- `--port <port>` 使用特定的本地回调端口
对于 CI 或非交互式环境，请使用 API 令牌：
```sh
export GITHITS_API_TOKEN=ghi-your-token-here
```
检查身份验证和运行时状态：
```sh
npx githits@latest auth status
npx githits@latest doctor
```
查看 [身份验证文档](https://docs.githits.com/authentication)，了解钥匙串行为、文件存储模式、CI 设置和故障排除。
## 手动 MCP 设置
如果您的编程工具未被 `init` 自动配置，请手动将 GitHits 添加到其 MCP 配置中：
```json
{
"mcpServers": {
"githits": {
"command": "npx",
"args": ["-y", "githits@latest", "mcp", "start"]
}
}
}
```
您的工具通过 stdio 运行此命令。不需要后台守护进程或全局安装。
要删除 `init` 编写的配置：
```sh
npx githits@latest init uninstall
```
这会删除 GitHits MCP 配置并保留存储的凭证。单独运行 `npx githits@latest logout` 以删除凭证。
## 项目设置
对于项目本地 MCP 配置，运行：
```sh
npx githits@latest init --project
```
项目设置仅适用于具有已验证的项目本地 MCP 支持的工具。项目配置不包含机密，但可以像其他工具配置一样提交，因此在将其添加到源代码控制之前，请查看生成的配置文件。
代理安全非交互式设置使用分段发现和显式安装：
```sh
npx githits@latest init --detect-agents --json
npx githits@latest init --install-agents cursor,codex
```
## 插件和扩展打包
npm 软件包还包括与兼容主机一起使用的现有插件和扩展资产：
- `.plugin/plugin.json`
- `.claude-plugin/plugin.json`
- `.claude-plugin/marketplace.json`
- `.mcp.json`
- `gemini-extension.json`
- `GEMINI.md`
- `plugins/claude/`
- `skills/`
- `commands/`
对于 Claude Code 市场安装：
```sh
claude plugin marketplace add githits-com/githits-cli
claude plugin install githits@githits-plugins
```
对于 Gemini CLI 扩展安装：
```sh
gemini extensions install https://github.com/githits-com/githits-cli
```
## 命令参考
```text
githits init 将 GitHits 连接到您的编程代理
githits init uninstall 删除 GitHits MCP 配置
githits login 登录到您的 GitHits 帐户
githits logout 删除存储的凭证
githits mcp 显示设置说明或启动本地 MCP 服务器
githits mcp start 始终通过 stdio 启动本地 MCP 服务器
githits example 从开源中查找现实世界的实现
githits languages 列出或筛选支持的编程语言
githits feedback 提交有关 GitHits 结果的反馈
githits doctor 诊断配置和身份验证状态
githits search 探索仓库代码、依赖关系、文档和符号
githits search-status 检查以前索引搜索的状态
githits code 列出、读取和 grep 索引依赖关系的源代码
githits pkg 检查软件包元数据、漏洞、依赖关系和变更日志
githits docs 浏览和读取软件包文档
githits auth 管理身份验证
githits auth status 显示身份验证状态
```
完整的 CLI 参考：https://docs.githits.com/cli/commands
## 环境变量
大多数用户不需要环境变量。这些是 CI、身份验证存储和本地诊断的常见覆盖：
| 变量 | 目的 | 默认值 |
| --- | --- | --- |
| `GITHITS_API_TOKEN` | 身份验证的 API 令牌 | 未设置 |
| `GITHITS_AUTH_STORAGE` | 重写 OAuth 存储模式：`keychain` 或 `file` | `keychain` |
| `GITHITS_DISABLE_UPDATE_CHECK` | 禁用 npm 最新版本更新通知 | 未设置 |
| `GITHITS_TELEMETRY` | 将本地时间诊断信息输出到 stderr | 未设置 |
完整参考：https://docs.githits.com/cli/environment-variables
## 源代码布局
此仓库包含 GitHits CLI 和可重用的 MCP 软件包：
- `src/` - CLI 命令、本地身份验证、设置流程和本地 MCP stdio 启动
- `packages/mcp/` - 公共的 `@githits/mcp` 软件包，用于传输中立的 MCP 服务器 API、工具注册、说明和烟雾测试助手
- `packages/core-internal/` - CLI 和 MCP 软件包使用的共享工作区实现
- `docs/` - 实现说明和贡献者指南
- `scripts/` - 软件包验证、烟雾测试和开发实用程序
## 开发
要求：
- Node.js `^20.12.0 || >=22.13.0`
- Bun
常见命令：
```sh
bun install
bun run dev --help
bun test
bun run typecheck
bun run build
```
更改 MCP 工具、CLI 命令、共享格式化程序、身份验证/错误信封或 MCP/CLI 奇偶校验行为时，还要运行相关的烟雾测试：
```sh
bun run smoke:mcp
bun run smoke:cli
```
更改 MCP 说明、工具描述或面向代理的行为时，请使用 `eval/agentic/README.md` 中描述的目标代理评估：
```sh
bun run agent:e2e
```
## 许可证
Apache-2.0
