内容
# godig - 命令行工具及 MCP 服务器，用于 pkg.go.dev
[](https://github.com/samber/godig/releases)
[](https://pkg.go.dev/github.com/samber/godig)
[](https://goreportcard.com/report/github.com/samber/godig)
[](https://github.com/samber/godig/graphs/contributors)
[](./LICENSE)
`godig` 是一个命令行工具 **和** MCP 服务器，用于通过 [pkg.go.dev](https://pkg.go.dev) API 探索 Go 包和模块：搜索、文档、符号、版本、导入者和漏洞 —— 从您的 shell 或 AI 代理。
其命令和 MCP 工具从一个小型手动编写的目录 (`internal/spec`) 构建，并调用类型化的 [`go-pkggodev-client`](https://github.com/samber/go-pkggodev-client)。所有操作均为只读，无需身份验证。
> [!TIP]
> 寻找一个 **Go 库** 而不是命令行工具？使用 [`samber/go-pkggodev-client`](https://github.com/samber/go-pkggodev-client) —— 为 `godig` 提供支持的 pkg.go.dev 客户端。
## 🚀 安装
```sh
go install github.com/samber/godig/cmd/godig@latest
# AI 代理技能：
npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev
# 将 MCP 服务器注册到 Claude Code（stdio）
claude mcp add pkg-go-dev -- godig mcp
```
需要 Go >= 1.25。参见 [技能](#-技能) 以将 MCP 服务器注册到您的代理。
## 💡 快速开始
```sh
# 概览 - 一个紧凑的调用：元数据、最新 + 最近版本、许可证、漏洞
godig overview github.com/samber/ro
# 搜索
godig search "result option monad" --limit 5
# 包方面
godig package info github.com/samber/ro
godig package imports github.com/samber/ro
godig package doc github.com/samber/ro --format md
godig package examples github.com/samber/ro
godig package examples github.com/samber/ro --symbol Map # 仅限一个符号的示例
godig package licenses github.com/samber/ro
# 单个符号（与完整的包文档/示例相比，令牌效率高）
godig symbol doc github.com/samber/ro Map
godig symbol examples github.com/samber/mo Either.ForEach
# 模块方面
godig module info github.com/samber/ro # 包括下载大小 + 最小 Go 版本
godig module readme github.com/samber/ro
godig module licenses github.com/samber/ro
godig dependencies github.com/samber/oops # go.mod 需要/替换/排除
# 列表（自动分页；--limit 限制，-o md 为 Markdown 表格）
godig versions github.com/samber/ro -o md
godig major-versions github.com/samber/do # v1, v2, v3 ...（独立模块）
godig major-versions github.com/samber/do --exclude-pseudo # 删除最新的伪版本
godig packages github.com/samber/ro
godig imported-by github.com/samber/ro --limit 20
godig symbols github.com/samber/ro
# 过滤器（一个 Go 布尔表达式，用于遍历项目字段）和构建上下文（goos/goarch）
godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")'
godig symbols github.com/samber/ro --goos linux --goarch amd64
# 漏洞
godig vulns github.com/samber/ro
# 作为 MCP 服务器运行（stdio；--transport http 为 HTTP）
godig mcp
```
全局标志：`-o, --output`（`table` 默认，`json`, `raw`, `md`），`--base-url`，`--timeout`，
`--log-level`（`debug|info|warn|error|off` 默认 `error`; 日志输出到 **stderr**）。
所有标志也可以通过 `GODIG_`-前缀的环境变量设置。
退出代码：`0` 成功，`1` 运行时错误（例如网络，包未找到），`2` 用法错误
（缺少/无效参数或标志，或在没有子命令的情况下调用命令）。
## 🧠 命令
| 命令 | 描述 |
| ----------------------------------------- | ------------------------------------ |
| `godig overview <路径>` | 一次调用的紧凑摘要（从这里开始）|
| `godig search <查询> [--symbol <s>]` | 搜索包和符号 |
| `godig package info <路径>` | 包元数据 |
| `godig package imports <路径>` | 包导入的包 |
| `godig package doc <路径> --format <格式>` | 包文档（md/text/html） |
| `godig package examples <路径>` | 文档和示例（ `--symbol` 限定范围） |
| `godig package licenses <路径>` | 包许可证 |
| `godig symbol doc <路径> <符号>` | 一个符号的签名 + 文档 |
| `godig symbol examples <路径> <符号>` | 一个符号的可运行示例 |
| `godig module info <路径>` | 模块元数据（包括大小 + 最小 Go 版本） |
| `godig module licenses <路径>` | 模块许可证 |
| `godig module readme <路径>` | 模块 README |
| `godig dependencies <模块>` | 模块依赖于其 go.mod |
| `godig packages <模块>` | 列出模块的包 |
| `godig versions <模块>` | 列出模块版本 |
| `godig major-versions <模块>` | 列出主版本（v1, v2, v3 ...） |
| `godig imported-by <路径>` | 导入包的包 |
| `godig symbols <路径>` | 包导出的符号 |
| `godig vulns <路径>` | 已知漏洞 |
| `godig mcp` | 运行 MCP 服务器（stdio 或 http） |
运行 `godig <命令> --help`（或 `godig package --help`）获取每个命令的标志。每个操作也作为 MCP 工具公开（例如 `overview`, `package-info`, `module-readme`）。实用命令：
`godig version` 和 `godig completion <shell>`（bash/zsh/fish/powershell）。
**对于 AI 代理（令牌效率高）：** 从 `overview` 开始 —— 一个调用返回一个紧凑的摘要
（无需大型文档）。仅在需要完整文本时，才获取 `doc`, `examples`, `module readme` 或 `licenses`，
并使用 `--limit` 限制长列表（`versions`, `imported-by`）。
## 🔎 过滤器
`--filter` 标志（在 `search`, `versions`, `packages`, `imported-by`, `symbols`, `vulns`,
`major-versions` 上）在服务器端对每个项目使用 **Go 布尔表达式** 进行求值。标识符是项目的字段 ——
**因命令而异**，因此一个列表中有效的字段在另一个列表中无效（例如 `search` 公开 `packagePath`，而非 `path`）。
辅助函数包括 `hasPrefix`, `hasSuffix` 和 `contains`。
```sh
godig search "result option" --filter 'hasPrefix(packagePath, "github.com/samber/")'
godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")'
godig symbols github.com/samber/ro --filter 'kind == "Function"'
godig imported-by github.com/samber/ro --filter 'contains(path, "/internal/")'
```
每个命令可用的字段（字符串除非另有说明）：
| 命令 | 可过滤字段 |
| ---------------- | --------------------------------------------------------------------------------- |
| `search` | `modulePath`, `packagePath`, `synopsis`, `version` |
| `versions` | `version`, `modulePath`, `deprecated`（布尔值），`retracted`（布尔值），`hasGoMod`（布尔值），`commitTime` |
| `packages` | `path`, `name`, `synopsis`, `isRedistributable`（布尔值） |
| `imported-by` | `path`（导入包的路径） |
| `symbols` | `name`, `kind`（`Function`/`Method`/`Type`/`Variable`/`Constant`），`synopsis`, `parent` |
| `vulns` | `ID`, `package`, `Details` |
| `major-versions` | `modulePath`, `major`, `version`, `isLatest`（布尔值） |
> [!NOTE]
> 标识符遵循 pkg.go.dev API 的过滤器模式，且大小写不统一 ——
> 大多数使用小写 JSON 字段名称，但 `vulns` 使用 Go 风格的名称（`ID`，而非 `id`）。
> `kind` 值大写（`Function`，而非 `func`）。未知标识符被 API 以 `HTTP 400 undefined identifier: <name>` 拒绝，
> 其中 `<name>` 为有问题的字段。
## 📫 MCP 服务器
`godig mcp` 运行一个 MCP 服务器，通过任一传输方式公开一个只读工具。
**stdio** （默认）- 客户端按需启动二进制文件：
```sh
claude mcp add pkg-go-dev -- godig mcp
```
```json
{ "mcpServers": { "pkg-go-dev": { "command": "godig", "args": ["mcp"] } } }
```
**可流式 HTTP** - 一个共享的、长时间运行的服务器在 `/mcp`（`--addr`，默认为 `:8080`）：
```sh
godig mcp --transport http --addr :8080
claude mcp add --transport http pkg-go-dev http://localhost:8080/mcp
```
```json
{ "mcpServers": { "pkg-go-dev": { "type": "http", "url": "http://localhost:8080/mcp" } } }
```
一个公共实例托管在 [Clever Cloud](https://www.clever.cloud) 上，位于 **`https://godig.samber.dev/mcp`** ——
在本地无需运行任何操作即可注册：
```sh
claude mcp add --transport http pkg-go-dev https://godig.samber.dev/mcp
```
```json
{ "mcpServers": { "pkg-go-dev": { "type": "http", "url": "https://godig.samber.dev/mcp" } } }
```
## 🥷 技能
一个配套的 AI 代理技能，**`golang-pkg-go-dev`**，位于 [samber/cc-skills-golang](https://github.com/samber/cc-skills-golang)。
它涵盖了设置（注册 MCP 服务器）和使用工作流（意图 → 命令/工具），并在探索 Go 包时触发：
文档、版本、导入者、漏洞。
```sh
npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev
```
## 🔧 工作原理
- `internal/spec` 是一个手动编写的操作目录（名称、标志、类型）。
- CLI（`cmd/godig`）和 MCP 服务器（`internal/mcpserver`）都通过遍历目录构建其表面 ——
每个操作一个 Cobra 命令和一个 MCP 工具。
- `internal/dispatch` 是共享的核心：它将每个操作名称映射到匹配的类型的 [`go-pkggodev-client`](https://github.com/samber/go-pkggodev-client) 调用；
结果渲染为 `table`, `json` 或 `raw`。
## 🤝 贡献
```sh
# 安装开发依赖
make tools
# 运行测试
make test
# 校验
make lint
# 构建（使用版本 ldflags）
make build
```
## 👤 贡献者
## 🙏 致谢
感谢 [Clever Cloud](https://www.clever.cloud) 托管公共 `godig.samber.dev` MCP 服务器。
## 💫 支持
如果这个项目对你有帮助，请给予 ⭐️ 支持！
[](https://github.com/sponsors/samber)
## 📝 许可证
Copyright © 2026 [Samuel Berthe](https://github.com/samber).
该项目使用 [MIT](./LICENSE) 许可证。
