gjczone/pi-shazam

# pi-shazam [](https://www.npmjs.com/package/pi-shazam) [](https://github.com/gjczone/pi-shazam/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) ## 功能介绍 **pi-shazam** 是一个为 **Pi coding agent** 打造的原生代码库分析工具包。它提供了 14 个结构化分析工具，帮助 AI agent 在阅读代码之前理解项目架构。 对于非 Pi agent，pi-shazam 也通过 **MCP (Model Context Protocol)** 暴露相同的工具。支持的 MCP 客户端包括 Cursor、Claude Code、Qoder、Trae、Codebuddy、Kimi Code 等。**注意：MCP 接口是一个兼容层 —— 主要且推荐的部署模式是作为原生的 Pi 扩展。** ## 核心能力 - **Tree-sitter 解析** — 支持 6 种编程语言（Python、TypeScript、JavaScript、Go、Rust、JSON），提供完整的符号依赖图 - **PageRank 排序** — 识别核心文件和关键符号 - **LSP 集成** — 类型检查、诊断、类型层级（支持 6 种语言） - **增量分析** — 基线比较，专注于变更内容 - **智能验证** — 编辑后的验证，提供 PASS/WARN/FAIL 结果 ## 快速开始 ### Pi Agent（默认 — 推荐） **这是主要的安装方法。** pi-shazam 首要为 Pi agent 设计和优化。 ``` pi install npm:pi-shazam ``` 安装后，所有 14 个分析工具都将作为原生的 Pi 工具与 `read`、`write` 和 `bash` 一同注册。自动 hook 会将项目结构注入到系统 prompt 中，在编辑后验证代码，并记录工具使用情况。**完整的 hook 生命周期（before_agent_start、session_start、session_shutdown、tool_call、tool_result）仅在 Pi 模式下可用。** ### MCP（仅适用于非 Pi Agent） 仅当你**没有**使用 Pi agent 时才使用此方法。MCP 接口提供相同的 14 个带有 LSP 支持的工具，但不包含 Pi 特定的 hook 和生命周期集成。 ``` { "mcpServers": { "pi-shazam": { "command": "npx", "args": ["-y", "-p", "pi-shazam", "pi-shazam-mcp"] } } } ``` 兼容任何支持 MCP 的客户端。相同的分析引擎，基于 JSON 的工具接口。 ## 工具 ### 查询（只读） | Tool | 功能描述 | | ----------------------- | ---------------------------------------------------------------------------------- | | `shazam_overview` | 项目结构、基于 PageRank 的前 10 个核心文件、关键依赖、最近的 commits | | `shazam_impact` | 变更影响分析（BFS 深度跟踪，默认为 3）：受影响的文件、符号、测试 | | `shazam_codesearch` | BM25 符号搜索 + ripgrep 全文搜索（target=symbol/code）— 排序版的 grep 替代方案 | | `shazam_symbol` | 符号定义、签名、调用者、被调用者 | | `shazam_hover` | 类型签名、JSDoc、用于函数调用上下文的 signatureHelp | | `shazam_file_detail` | 文件结构：符号、PageRank、调用次数、LSP 层级、codeLens 引用 | | `shazam_call_chain` | 完整的上游/下游调用图 | | `shazam_find_tests` | 查找覆盖某个模块的测试文件 | | `shazam_hotspots` | 按复杂度排序的文件 — 最容易产生严重 bug 的地方 | | `shazam_type_hierarchy` | 类/接口继承链 + 实现位置 | ### 编写与验证 | Tool | 功能描述 | | ---------------------- | --------------------------------------------------------------------------- | | `shazam_verify` | 编辑后的验证：LSP 诊断 + codeAction 修复 + 风险 + 孤立代码 | | `shazam_fix` | 自动修复格式问题（prettier、biome、eslint、ruff、gofmt） | | `shazam_rename_symbol` | 安全的项目级重命名 — 首先验证引用 | | `shazam_safe_delete` | 确认零引用后删除 | ## 平台支持 ### Pi Agent Hooks | Hook | 事件 | 功能描述 | | ------------------ | --------------------------- | -------------------------------------------------------------------------------------------- | | `before-start` | `before_agent_start` | 将项目结构概览 + 主动建议注入到系统 prompt 中 | | `safety` | `tool_call` (bash) | 破坏性命令确认对话框 + Pre-commit 门控（没有 verify 则阻止 git commit） | | `shazam-guide` | `tool_result` | 写入/编辑后自动格式化文件 + 上下文工具建议 | | `stop-verify` | `turn_end` | 提醒在结束对话前运行 `shazam_verify` | | `failure-recovery` | `tool_result` | 检测连续失败（3次/5次）并建议替代方案 | | `pre-edit` | `tool_call` | 检测多文件编辑，警告其影响范围 | | `tool-logger` | `tool_call` + `tool_result` | 将所有 shazam 工具调用记录到 `~/.pi/hooks/audit/shazam-calls.log` | | `issue-guard` | `tool_call` (bash) + `tool_result` | 检测 `gh issue create`，在运行 `shazam_impact` 之前阻止编辑 | | `agent-context-guard` | `tool_call` (agent) | 对于审查任务，在没有结构化上下文的情况下阻止 agent 生成 | **自动格式化支持**: ruff (Python), prettier (JS/TS/JSON/MD), gofmt (Go), rustfmt (Rust), biome (JS/TS) 附加命令：`/shazam-setup`, `/shazam-doctor`, `/shazam-install-git-hooks`, `/shazam-remove-git-hooks`, `/shazam-pre-commit-verify` ### MCP 客户端支持 pi-shazam 的 MCP 服务器支持所有兼容 MCP 的客户端： - **Cursor** — 内置 MCP 支持 - **Claude Code** — Anthropic 的 coding agent (CLI) - **Qoder** — AI coding assistant - **Trae** — ByteDance 的 AI coding IDE - **Codebuddy** — Tencent 的 AI coding assistant - **Kimi Code** — Moonshot AI coding assistant - **其他** — 任何实现了 MCP 协议的工具 ## 平台与构建 ### npm 自动构建 pi-shazam 通过 npm 发布，具有自动平台支持： | 平台 | 架构 | 状态 | | --------- | ---------------------------------- | --------------- | | **Linux** | x64, arm64 | 完全支持 | | **macOS** | x64 (Intel), arm64 (Apple Silicon) | 完全支持 | ### 依赖项 pi-shazam 使用 `tree-sitter` 进行代码解析，这是一个原生的 Node.js 模块。npm 会在安装过程中自动为你的平台编译二进制文件 —— 无需手动操作。 支持 Node.js 版本：**>= 18.0.0** ### 社区格式/版本支持 - **TypeScript**: `.ts`, `.tsx`, `.mts`, `.cts` - **JavaScript**: `.js`, `.jsx`, `.mjs`, `.cjs` - **Python**: `.py`, `.pyi` - **Go**: `.go` - **Rust**: `.rs` - **数据格式**: `.json` ## 架构 ``` pi-shazam (npm package) │ ├── hooks/ Automatic hooks (hooks → tools → core) │ ├── before-start.ts Inject project overview into system prompt │ ├── safety.ts Destructive command confirmation + pre-commit gate │ ├── pre-edit.ts Multi-file edit protection │ ├── shazam-guide.ts Auto-format + tool usage guidance │ ├── stop-verify.ts Turn-end verification reminder │ ├── failure-recovery.ts Consecutive failure detection │ ├── tool-logger.ts Usage analytics │ ├── verify-state.ts Shared verify tracking state for safety + stop-verify │ ├── impact-state.ts Shared impact tracking state for issue-guard + pre-edit │ ├── issue-guard.ts Detect gh issue create, set pending impact flag │ └── agent-context-guard.ts Block agent spawn without structural context │ ├── tools/ Pi tool wrappers (tools → core + lsp) │ ├── definitions.ts Shared tool definitions (names, descriptions, schemas) │ ├── _factory.ts Tool registration factory │ ├── _context.ts Shared LSP manager holder │ ├── lsp_enrich.ts LSP enrichment wrappers │ ├── overview.ts ─── impact.ts ─── codesearch.ts │ ├── symbol.ts ─── hover.ts ─── file_detail.ts │ ├── call_chain.ts ─── verify.ts ─── fix.ts │ ├── hotspots.ts ─── find_tests.ts ─── type_hierarchy.ts │ ├── rename_symbol.ts ─── safe_delete.ts │ │ │ └── Pi Extension (index.ts) MCP Server (mcp/entry.ts ── mcp/tools.ts) │ │ │ │ └────────── core/ + lsp/ ───────────┘ │ (shared engine, zero duplication) │ ├── lsp/ Language server management │ ├── manager.ts Server lifecycle (spawn, stdio, health, shutdown) │ ├── client.ts LSP protocol via vscode-jsonrpc │ ├── servers.ts Language → server config (6 languages) │ └── setup.ts /shazam-setup command │ └── core/ Pure analysis engine (zero dependencies) ├── treesitter.ts AST parsing + symbol extraction (6 languages) ├── treesitter-queries.ts Tree-sitter query patterns ├── graph.ts Symbol dependency graph ├── pagerank.ts PageRank symbol importance scoring ├── scanner.ts Project file scanning + graph building ├── encoding.ts UTF-8 → GBK → GB2312 adaptive encoding ├── cache.ts Graph baseline save/diff + persistent cache ├── baseline.ts In-memory session baseline ├── filter.ts Shared file filtering (source vs config/generated) ├── output.ts Standardized tool output formatting └── git-hooks.ts Git pre-commit hook management ``` ## 开发 ``` git clone https://github.com/gjczone/pi-shazam.git cd pi-shazam npm install --legacy-peer-deps npm run dev # tsc --watch npm run typecheck # tsc --noEmit npm test # vitest npm run build # tsc → dist/ ``` ## LSP 支持 | 语言 | LSP 服务器 | 状态 | | --------------------- | -------------------------- | --------- | | TypeScript/JavaScript | typescript-language-server | 支持 | | Python | pyright-langserver / pylsp | 支持 | | Go | gopls | 支持 | | Rust | rust-analyzer | 支持 | | YAML | yaml-language-server | 支持 | | JSON | vscode-json-languageserver | 支持 | 当 LSP 服务器不可用时，工具会自动回退到 tree-sitter 模式。 ## 许可证 MIT ## 链接 - [npm](https://www.npmjs.com/package/pi-shazam) - [GitHub](https://github.com/gjczone/pi-shazam) - [Pi Agent](https://pi.dev) - [MCP 协议](https://modelcontextprotocol.io)

标签：AI编程助手, IDE插件, MITM代理, SOC Prime, Tree-sitter, 云安全监控, 代码分析, 凭证管理, 开发工具, 模型上下文协议, 自动化攻击, 静态分析