nsrosenqvist/nitpik
GitHub: nsrosenqvist/nitpik
一款支持自带模型、可集成至任意 CI 的 AI 代码审查工具，提供多视角代码质量与安全分析。
Stars: 2 | Forks: 1
# nitpik
**个人使用和开源使用永久免费。** 无需许可证密钥 —— 只需安装即可运行。
为您的团队提供 AI 驱动的代码审查。自带模型，自带 API 密钥。支付单一固定平台费用 —— 无按席位收费，无使用量限制。
[官网](https://nitpik.dev) · [文档](https://github.com/nsrosenqvist/nitpik/wiki) · [安全模型](https://github.com/nsrosenqvist/nitpik/wiki/13-Security-Model) · [获取许可证](https://nitpik.dev) · `nitpik help`
## 为什么选择 nitpik？
- **自带模型** — 支持 Anthropic、OpenAI、Gemini、Cohere、DeepSeek、xAI、Groq、Perplexity 或任何兼容 OpenAI 的 API。您的密钥、您的基础设施、您的数据。
- **统一平台费** — 为整个团队支付一份价格。无按席位授权，无基于使用量的计费，没有隐形消费。
- **个人和开源免费** — 可永久免费在个人项目和开源仓库中使用 nitpik。无需许可证密钥。
- **单一二进制文件 + Docker 镜像** — 几分钟内即可将其集成到任何 CI pipeline 中。
- **可配置的审查者 agent** — 内置配置文件，或通过自定义 Markdown 定义符合您团队规范的审查者。
- **Agentic 模式** — 让 LLM 使用内置和自定义工具探索您的代码库。
- **机密扫描** — 200+ 条规则可在代码发送至 LLM 之前检测并隐去机密信息。
- **威胁扫描** — 44 条规则加上结构化启发式算法，可检测混淆的 payload、后门、供应链攻击、不可见的 Unicode 技巧以及同形字标识符。
- **支持所有主流 CI 平台** — GitHub Actions、GitLab CI、Bitbucket Pipelines、Woodpecker/Forgejo/Gitea。
## 快速开始
### 1. 安装
**安装脚本（推荐）**
```
curl -sSfL https://raw.githubusercontent.com/nsrosenqvist/nitpik/main/install.sh | bash
```
该脚本会检测您的系统平台，下载最新版本的发布包，校验 checksum，并将二进制文件安装到 `/usr/local/bin`。您可以传入选项以进行自定义：
```
# 安装到自定义目录
curl -sSfL https://raw.githubusercontent.com/nsrosenqvist/nitpik/main/install.sh | bash -s -- --dir ~/.local/bin
# 安装特定版本
curl -sSfL https://raw.githubusercontent.com/nsrosenqvist/nitpik/main/install.sh | bash -s -- --version v0.3.0
```
**Homebrew（macOS 和 Linux）**
```
brew tap nsrosenqvist/nitpik
brew install nitpik
```
或者从源码构建：
```
cargo install --path .
```
安装完成后，您可以随时更新至最新版本：
```
nitpik update
```
**Docker**
```
docker pull ghcr.io/nsrosenqvist/nitpik:latest
```
### 2. 激活您的许可证（仅限商业用途）
若用于商业用途，请激活您的许可证密钥：
```
nitpik license activate
nitpik license status # verify activation
```
该密钥将存储在 `~/.config/nitpik/config.toml` 中。您也可以在 CI 中设置 `NITPIK_LICENSE_KEY` 环境变量。
**个人和开源项目无需许可证密钥。**
### 3. 连接 LLM 提供商
nitpik 采用自带模型策略。设置两个环境变量 —— 一个提供商名称和相应的 API 密钥：
```
export NITPIK_PROVIDER=anthropic # or openai, gemini, cohere, deepseek, xai, groq, mistral, ollama, and more
export ANTHROPIC_API_KEY=sk-... # provider-specific key
```
或者使用 `NITPIK_API_KEY` 作为通用的后备选项。要使用自定义或自托管 endpoint（任何兼容 OpenAI 的 API），还需设置 `NITPIK_BASE_URL`。
### 4. 运行您的首次审查
```
nitpik review --diff-base main
```
就是这样。nitpik 会将您当前的分支与 `main` 分支进行 diff，选择一个审查者配置文件，扫描机密信息，并将结果打印到您的终端：
```
nitpik · Free for personal & open-source use. Commercial use requires a license.
✔ w/handler.rs done
✖ error in handler.rs:21
Backend crashes due to unhandled file I/O and parsing errors — The
`load_users` function uses `unwrap()` for file reading and parsing,
and accesses array elements without bounds checking.
→ Implement robust error handling (e.g., using `Result` and propagating
errors) instead of `unwrap()`. Add bounds checking for array access.
⚠ warning in handler.rs:36
N+1 query in `get_users_by_ids` — Calling `get_user` in a loop for
each ID results in an N+1 query pattern, leading to significant
performance degradation for large ID lists.
→ Consider implementing a batch fetch mechanism that retrieves all
users in a single operation.
───────────────────────────────────
2 findings: 1 errors, 1 warnings, 0 infos
```
## 核心概念
### Diff 输入
nitpik 需要一个 diff 进行审查。请根据您的工作流程选择合适的方式：
```
nitpik review --diff-base main # git diff against a branch/commit
nitpik review --scan src/main.rs # review a file directly (no git)
nitpik review --diff-file changes.patch # pre-computed unified diff
git diff main | nitpik review --diff-stdin # piped from another tool
```
### 审查视角
nitpik 通过**视角**进行审查 —— 即特定问题类型的专门审查者，每个视角负责排查一类完全独立的问题。其中两个视角始终运行；其余视角则由 diff 实质分类步骤根据每次代码改动来决定是否运行：
| 视角 | 负责排查 | 运行时机 |
|---|---|---|
| `security` | 注入、authZ、机密信息、输入验证、加密 | 始终运行 |
| `correctness` | 逻辑错误、差一错误、错误处理、边界情况、不变量 | 始终运行 |
| `concurrency` | 竞态条件、死锁、共享可变状态 | 条件触发 |
| `performance` | N+1 查询、热路径分配、复杂度、延迟 | 条件触发 |
| `test-integrity` | 变更行为覆盖率、确定性、同义反复测试 | 条件触发 |
| `operational` | 可观测性、迁移、feature flag、配置/机密信息 | 条件触发 |
| `a11y` | 语义、ARIA、键盘导航、对比度、标签 | 条件触发 |
| `user-journey` | UX 正常路径 + 失败模式走查 | 条件触发 |
| `contract-impact` | 重命名/签名连带影响、跨文件 API/向后兼容 | 条件触发 |
| `docs-drift` | 文档/注释/OpenAPI 不再匹配变更后的行为 | 条件触发 |
| `holistic` | 整个 PR 的一致性、对称性义务 | 条件触发 |
运行指定集合，或让 `auto`（默认值）自动选择：
```
nitpik review --diff-base main # auto: always-on + triaged lenses
nitpik review --diff-base main --profile security,performance # exactly these
```
使用 `--profile auto`（未指定标志时的默认值）时，将运行两个常驻视角，同时分类步骤会根据改动的实质（而不仅仅是文件类型）选择符合条件的条件性视角：
```
nitpik review --diff-base main --profile auto
```
通过标签选择视角 —— 标签匹配的所有配置文件（内置和自定义）都将被包含在内：
```
nitpik review --diff-base main --tag security # everything tagged "security"
nitpik review --diff-base main --tag accessibility,performance # union of both tags
```
将 `--tag` 与 `--profile` 结合使用，可以在显式指定集合的基础上添加标签匹配的审查者：
```
nitpik review --diff-base main --profile correctness --tag performance
```
标签匹配不区分大小写。有关如何在自定义配置上设置标签，请参阅[自定义 Agent 配置文件](#custom-agent-profiles)。
列出所有可用的配置文件（包括自定义文件）：
```
nitpik profiles
nitpik profiles --profile-dir ./agents
```
### 输出格式
| 格式 | 标志 | 用例 |
|---|---|---|
| 样式化终端 | `--format terminal` | 本地开发（默认） |
| JSON | `--format json` | 自定义工具 / 仪表板 |
| GitHub 批注 | `--format github` | GitHub Actions |
| GitLab 代码质量 | `--format gitlab` | GitLab CI 合并请求小部件 |
| Bitbucket 代码洞察 | `--format bitbucket` | Bitbucket Pipelines |
| Checkstyle XML | `--format checkstyle` | Jenkins、reviewdog、Bitbucket Pipes 以及任何支持读取 checkstyle 的工具 |
| Forgejo/Gitea PR 审查 | `--format forgejo` | Woodpecker CI / Forgejo / Gitea（需要 `FORGEJO_TOKEN`） |
默认情况下，遇到 `error` 严重级别的发现时，nitpik 会以非零状态码退出 —— 就像标准的测试运行器和 linter 一样。您可以调整阈值或禁用此行为：
```
nitpik review --diff-base main --format github --fail-on warning # also fail on warnings
nitpik review --diff-base main --no-fail # always exit 0
```
运行 `nitpik help review` 以获取完整的标志列表。
### 智能审查编排
nitpik 不仅仅是将您的 diff 丢给 LLM 然后祈祷最好的结果。每一次审查都经过精心编排，以最大化精确度并最小化噪音：
- **全上下文感知** — LLM 能够看到完整的文件（对于大文件则是智能摘录）、您项目的规范、提交历史以及聚焦的 diff —— 因此它能理解发生了什么变化以及为什么重要。
- **多 agent 协调** — 当多个审查者配置并行运行时，每一个都知道其他配置覆盖的范围并各司其职，从而消除重复的发现并确保没有任何遗漏。
- **多波次审查（可选）** — `--multi-wave` 允许配置在其 frontmatter 中声明 `wave: 2`，以便在第 1 波次之后运行并对其发现做出反应。这对于受益于先查看其他视角发现的后期审查者（例如 `holistic` 视角）非常有用。
- **自动配置选择** — `auto` 是默认的配置（无需标志）：启发式算法从 diff 中挑选审查者。使用 `--auto-mode heuristic|llm|hybrid` 调整策略（默认的 `hybrid` 会优先使用启发式算法，仅在启发式算法结果不确定时，才回退到内置的 `triage` LLM 调用）。传入 `--profile ` 可进行覆盖。
- **评审者验证（可选）** — `--verify` 会在去重之后运行一个视角多样化的评审小组：三个独立的视角（平衡性、可靠性、依据性）并行对每个发现进行保留/丢弃投票，仅多数赞成时才丢弃发现（对于跨视角相互印证的发现，需一致同意才会被丢弃）。这可以在抑制可能存在的误报的同时，通过跨多样化视角的投票来防范任何单一 prompt 的盲点。添加 `--show-dropped` 可以查看小组丢弃了什么以及原因。
- **迭代连续性** — 当您推送新的更改时，nitpik 会延续之前审查的上下文，以便 LLM 能够区分已解决的问题和持续存在的问题，从而在代码演进过程中保持反馈的一致性。
- **质量后处理** — 发现的结果会跨 agent 进行去重（使用共享的证据片段作为合并信号之一），过滤为仅针对您实际修改的行，并在呈现给您之前进行严重性级别的标准化处理。最终结果是：可操作的发现，而不是 LLM 的噪音。
## 配置
设置是分层的 —— 每一层都会覆盖其下层的配置：
**CLI 标志 → 环境变量 → `.nitpik.toml`（仓库） → `~/.config/nitpik/config.toml`（全局） → 默认值**
### 项目配置（`.nitpik.toml`）
将其放在您的仓库根目录下，即可为团队中的所有人设置默认配置：
```
[provider]
name = "anthropic"
model = "claude-sonnet-4-20250514"
[review]
default_profiles = ["security", "correctness"]
fail_on = "warning"
[review.agentic]
enabled = false
max_turns = 10
max_tool_calls = 10
[review.context]
max_file_lines = 1000
surrounding_lines = 100
[secrets]
enabled = false
severity = "warning"
[threats]
enabled = false
```
### 环境变量
| 变量 | 用途 |
|---|---|
| `NITPIK_PROVIDER` | LLM 提供商（`anthropic`、`openai`、`gemini` 等） |
| `NITPIK_MODEL` | 模型名称（例如 `claude-sonnet-4-20250514`） |
| `NITPIK_API_KEY` | 通用 API 密钥后备 |
| `NITPIK_BASE_URL` | 兼容 OpenAI 的 API 的自定义 endpoint |
| `NITPIK_LICENSE_KEY` | 许可证密钥（作为 `nitpik license activate` 的替代方案） |
| `NITPIK_AUDIT_LOG` | 写入单次运行 JSON 审计日志的路径（相当于 `--audit-log`） |
| `ANTHROPIC_API_KEY` | Anthropic 专用密钥 |
| `OPENAI_API_KEY` | OpenAI 专用密钥（也用于兼容 openai 的 API） |
| `GEMINI_API_KEY` | Gemini 专用密钥 |
| `BITBUCKET_TOKEN` | Bitbucket 访问令牌（在 Bitbucket Pipelines 内可选） |
| `FORGEJO_TOKEN` | Forgejo/Gitea API 令牌（使用 `--format forgejo` 时必填） |
如果存在特定于提供商的环境变量，nitpik 会尝试优先使用该变量，并回退到 `NITPIK_API_KEY`。
## 自定义 Agent 配置
创建一个带有 YAML frontmatter 的 Markdown 文件来定义您自己的审查者。有关如何构建高效审查 prompt 的实际示例，请参阅[内置配置文件](src/agents/builtin/)。
```
---
name: team-conventions
description: Enforces our internal coding standards
model: claude-sonnet-4-20250514 # optional model override
tags: [style, conventions]
agentic_instructions: > # optional — only used in --agent mode
Use `search_text` to find other usages of renamed symbols and verify
they follow the new naming convention.
---
You are a code reviewer enforcing our team's conventions.
Check for:
- snake_case functions, PascalCase types
- Result-based error handling (no unwrap in production)
- Doc comments on all public items
```
`tags` 字段允许您使用 `--tag` 来代替（或 alongside）`--profile` 选择此配置：
```
# 选择每个标记为 "style" 的 profile — 包括上面的 team-conventions
nitpik review --diff-base main --profile-dir ./agents --tag style
```
多个配置可以共享标签。例如，如果两个自定义配置都标记为 `ui`，运行 `--tag ui` 将同时选择它们（以及任何同样带有该标签的内置视角，如 `a11y`）。
通过路径直接使用它，或者将其放在目录中并通过名称引用：
```
nitpik review --diff-base main --profile ./team-conventions.md
nitpik review --diff-base main --profile-dir ./agents --profile team-conventions
```
如果自定义配置的 `name` 与内置视角（`security`、`correctness`、`performance`、`a11y` 等）匹配，当设置了 `--profile-dir` 时，它将替换该视角 —— 这对于根据您的团队调整自带视角而无需 fork 项目非常有用。在配置的 frontmatter 中设置 `always_include: true` 即可在每次 `auto` 审查中运行它（内置的 `security` 和 `correctness` 视角即使用此设置），或者设置 `auto_candidate: true` 将其添加到条件分类池中。详情请参阅[自定义配置 → 覆盖内置视角](docs/07-Custom-Profiles.md#overriding-built-in-lenses)和[常驻配置](docs/07-Custom-Profiles.md#always-on-profiles)。
在使用前验证配置：
```
nitpik validate ./team-conventions.md
```
### 自定义 Agentic 工具
配置可以定义供 LLM 在 agentic 审查期间调用的 CLI 工具。在 frontmatter 中添加 `tools` 部分：
```
---
name: test-aware-reviewer
description: Reviews code and can run the test suite
tools:
- name: run_tests
description: Run the test suite with an optional filter
command: cargo test
parameters:
- name: filter
type: string
description: Test name filter
required: false
---
You are a reviewer that validates changes against the test suite...
```
当启用了 `--agent` 时，LLM 可以调用 `run_tests`（连同内置的 `read_file`、`search_text` 和 `list_directory` 具）来探索代码库并收集上下文。
```
nitpik review --diff-base main --profile ./test-aware-reviewer.md --agent
```
### 环境变量透传
自定义命令工具运行在采用**白名单**模型的沙箱子进程中：仅继承必要的系统变量（`PATH`、`HOME`、`SHELL`、`TERM`、`LANG`、`USER`、如 `LC_*` 的区域设置前缀，以及如 `XDG_*` 的 XDG 目录）。其他所有内容 —— API 密钥、令牌、数据库凭据、CI 密钥 —— 默认都会被剥离。这可以防止凭据意外泄露给 LLM 调用的命令。
如果您的自定义工具需要额外的环境变量（例如用于向 Jira、Docker 或 AWS 进行身份验证），请在配置的 `environment` frontmatter 字段中声明它们：
```
---
name: infra-reviewer
description: Reviews infrastructure changes
environment:
- JIRA_TOKEN
- AWS_* # prefix glob — matches AWS_REGION, AWS_SECRET_ACCESS_KEY, etc.
- DOCKER_HOST
tools:
- name: deploy_check
description: Check deployment status
command: curl -sH "Authorization: Bearer $JIRA_TOKEN" https://jira.example.com/status
---
You are an infrastructure reviewer...
```
支持确切的名称和前缀通配符（以 `*` 结尾）。除非在 `environment` 中明确列出，否则所有不在默认安全集合中的环境变量都将被剥离。
## CI / CD 集成
### Docker
官方镜像预装了 `git` 和 `nitpik` 二进制文件。挂载您的仓库并传入环境变量：
```
docker run --rm \
-v "$(pwd)":/repo \
-e NITPIK_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY \
-e NITPIK_LICENSE_KEY \
ghcr.io/nsrosenqvist/nitpik:latest review --diff-base main --scan-secrets
```
### GitHub Actions
最简单的方法 —— 使用官方 action：
```
on: pull_request
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/cache/restore@v4
with:
path: ~/.config/nitpik/cache
key: nitpik-${{ github.repository }}
- uses: nsrosenqvist/nitpik@v3
with:
profiles: security,performance
fail_on: warning
scan_secrets: "true"
env:
NITPIK_PROVIDER: ${{ vars.NITPIK_PROVIDER }}
NITPIK_MODEL: ${{ vars.NITPIK_MODEL }}
NITPIK_API_KEY: ${{ secrets.NITPIK_API_KEY }}
NITPIK_LICENSE_KEY: ${{ secrets.NITPIK_LICENSE_KEY }}
- uses: actions/cache/save@v4
if: always()
with:
path: ~/.config/nitpik/cache
key: nitpik-${{ github.repository }}
```
该 action 会自动检测 PR 目标分支，下载二进制文件，并将发现的结果输出为行内批注。
发现结果将作为行内批注显示在 pull request 中。
### GitLab CI/CD
```
code-review:
stage: test
image: ghcr.io/nsrosenqvist/nitpik:latest
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
script:
- git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
- nitpik review
--diff-base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
--profile security,performance
--format gitlab
--fail-on warning
--scan-secrets
> gl-code-quality-report.json
cache:
key: nitpik
paths:
- .nitpik-cache/
when: always
artifacts:
reports:
codequality: gl-code-quality-report.json
variables:
NITPIK_PROVIDER: anthropic
ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
NITPIK_LICENSE_KEY: $NITPIK_LICENSE_KEY
XDG_CONFIG_HOME: $CI_PROJECT_DIR/.nitpik-cache
```
发现结果将显示在合并请求的 Code Quality 小部件中。
### Bitbucket Pipelines
`bitbucket` 格式通过 Bitbucket API 将发现的结果作为 Code Insights 批注发布。在 Bitbucket Pipelines 内，身份验证是通过内置代理自动处理的 —— 无需令牌。
```
definitions:
caches:
nitpik: /root/.config/nitpik/cache
pipelines:
pull-requests:
'**':
- step:
image: ghcr.io/nsrosenqvist/nitpik:latest
caches:
- nitpik
script:
- git fetch origin "$BITBUCKET_PR_DESTINATION_BRANCH"
- nitpik review
--diff-base "origin/$BITBUCKET_PR_DESTINATION_BRANCH"
--profile security,backend
--format bitbucket
--fail-on error
--scan-secrets
variables:
NITPIK_PROVIDER: anthropic
ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
NITPIK_LICENSE_KEY: $NITPIK_LICENSE_KEY
```
### Woodpecker CI (Forgejo / Gitea / Codeberg)
`forgejo` 格式通过 Forgejo/Gitea API 将发现的结果作为行内 PR 审查评论发布。这需要一个至少包含 **`write:repository`** 权限范围的**个人访问令牌**。
在您的 Forgejo 或 Gitea 实例中的 **用户设置 → 应用程序 → 生成新令牌** 下创建一个令牌。将其添加为名为 `forgejo_token` 的 Woodpecker 密钥，以便在运行时将其暴露为 `FORGEJO_TOKEN`。
```
when:
event: pull_request
steps:
- name: ai-review
image: ghcr.io/nsrosenqvist/nitpik:latest
commands:
- git fetch origin "$CI_COMMIT_TARGET_BRANCH"
- nitpik review
--diff-base "origin/$CI_COMMIT_TARGET_BRANCH"
--profile security,performance
--format forgejo
--fail-on warning
--scan-secrets
secrets: [forgejo_token, anthropic_api_key, nitpik_license_key]
environment:
NITPIK_PROVIDER: anthropic
volumes:
- nitpik-cache:/root/.config/nitpik/cache
```
## 机密扫描
nitpik 内置了 200 多条兼容 gitleaks 的规则和香农熵检查。启用后，会在将**任何**代码发送给 LLM 之前检测并隐去机密信息。
```
nitpik review --diff-base main --scan-secrets
```
在 CI 中默认始终开启：
```
# .nitpik.toml
[secrets]
enabled = true
```
引入您自己的规则：
```
nitpik review --diff-base main --scan-secrets --secrets-rules ./custom-rules.toml
```
## 威胁扫描
nitpik 使用 44 条内置规则和结构化启发式算法检测潜在的有害代码模式 —— 混淆的 payload、危险的 API 调用、供应链钩子、后门和数据外泄。配置了 LLM 提供商后，被标记的模式会由模型进行分类处理，以减少误报。
```
nitpik review --diff-base main --scan-threats
```
除了 regex 规则之外，nitpik 还可以检测**不可见的 Unicode**字符（零宽空格、被 Glassworm 使用的韩文填充 payload）、**木马源**双向覆盖（CVE-2021-42574），以及**混合脚本同形字标识符** —— 即将西里尔字母或希腊字母等外观相似的字符混入拉丁字母标识符中，从而创建出视觉上完全相同但语义不同的符号。
启用威胁和机密扫描以实现最大程度的覆盖：
```
nitpik review --diff-base main --scan-secrets --scan-threats
```
在 CI 中默认始终开启：
```
# .nitpik.toml
[threats]
enabled = true
```
引入您自己的规则：
```
nitpik review --diff-base main --scan-threats --threat-rules ./custom-threats.toml
```
## 项目文档上下文
nitpik 会自动检测您仓库根目录下的文档文件，并将它们包含在审查 prompt 中，以便 LLM 了解您团队的规范。
### 优先审查上下文（`REVIEW.md` / `NITPIK.md`）
如果仓库根目录下存在 **`REVIEW.md`** 或 **`NITPIK.md`** 文件，nitpik 将*仅*使用这些文件作为审查上下文，并完全跳过通用文档列表。这使您能够提供集中的审查指南，避免使用与审查者无关的编码 agent 指令（如 `AGENTS.md` 或 `.cursorrules`）污染 prompt。
这两个文件可以共存 —— 如果同时存在，则两者都会被包含。
### 通用后备文档
如果未找到优先文件，nitpik 将回退到扫描以下知名文件：
`AGENTS.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONTRIBUTING.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`, `CODING_GUIDELINES.md`, `STYLE_GUIDE.md`, `DEVELOPMENT.md`
超过 256 KB 的文件将被跳过。
### 控制项目文档
| 标志 | 默认值 | 效果 |
|---|---|---|
| `--no-project-docs` | `false` | 跳过所有自动检测到的项目文档文件 |
| `--exclude-doc ` | *(无)* | 通过文件名排除特定文档（以逗号分隔） |
跳过所有项目文档（有助于减小 prompt 大小或成本）：
```
nitpik review --diff-base main --no-project-docs
```
仅排除特定文件，同时保留其他文件：
```
nitpik review --diff-base main --exclude-doc AGENTS.md
nitpik review --diff-base main --exclude-doc AGENTS.md,CONTRIBUTING.md
```
## 提交历史上下文
在审查 git ref diff (`--diff-base`) 时，nitpik 会将 base 和 HEAD 之间的提交日志包含在审查 prompt 中。这使 LLM 能够洞察更改背后的*意图* —— 提交信息解释了代码更改的*原因*，有助于审查者校准严重性级别，并避免标记刻意的重构或修复。
最多会自动包含 50 条提交摘要（优先显示最新记录）。此功能仅适用于 `--diff-base` 模式 —— stdin diff、diff 文件和目录扫描由于没有提交历史，因此不包含在内。
| 标志 | 默认值 | 效果 |
|---|---|---|
| `--no-commit-context` | `false` | 跳过将提交摘要注入审查 prompt |
当提交信息包含大量噪音或为了减少 token 使用量时，可以禁用提交上下文：
```
nitpik review --diff-base main --no-commit-context
```
## 缓存
nitpik 通过内容哈希来缓存审查结果。未更改的文件不会被重新审查，从而节省时间和 API 成本。
当文件发生更改且缓存失效时，nitpik 会自动将**之前的发现**包含在 LLM prompt 中。这使模型能够区分已解决的问题、持续存在的问题或新出现的问题，从而提高对同一文件进行连续审查的一致性。
### 基于分支的先前发现结果
先前发现的结果会按**分支**进行跟踪，这样并行审查同一文件的 PR 就不会发生交叉污染。nitpik 通过 `git rev-parse --abbrev-ref HEAD` 检测分支，并在处于游离 HEAD（detached-HEAD）模式下运行时，回退到 CI 环境变量（`GITHUB_HEAD_REF`、`CI_COMMIT_BRANCH`、`CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`、`BITBUCKET_BRANCH`、`CI_BRANCH`）。
先前的发现结果在注入前会按严重性（错误优先）进行排序，从而确保始终保留最重要的上下文。
### 过期的 sidecar 清理
超过 **30 天**的 sidecar 元数据文件会在每次审查运行开始时自动删除，防止缓存在分支合并或删除后无限增长。
```
nitpik cache stats # show entry count and size
nitpik cache clear # wipe the cache (including all sidecar metadata)
nitpik cache path # print the cache directory
```
| 标志 | 默认值 | 效果 |
|---|---|---|
| `--no-cache` | `false` | 在此运行中完全禁用缓存 |
| `--no-prior-context` | `false` | 在缓存失效时跳过注入先前的发现结果 |
| `--max-prior-findings ` | 无限制 | 限制包含在 prompt 中的先前发现结果数量 |
使用 `--no-cache` 禁用单次运行的缓存。使用 `--no-prior-context` 可进行不带先前发现上下文的全新审查，或者在之前的审查产生了大量发现结果时使用 `--max-prior-findings` 来限制 prompt 的 token 使用量。
## 限制与免责声明
nitpik 使用第三方大型语言模型（LLM）来分析代码。**所有发现结果均由 AI 生成且仅供参考。** 它们可能是不正确的、不完整的或虚构的。nitpik 不保证代码的质量、安全性或正确性。
- **在采取行动之前，请务必运用人类判断力来审查 AI 的建议。**
- **代码 diff 会被发送到您配置的 LLM 提供商**（例如 Anthropic、OpenAI、Gemini）。nitpik 不会存储或保留您的代码，但需遵守 LLM 提供商的数据政策。请选择您信任其条款的提供商。有关 nitpik 本身收集的数据详细信息，请参阅[隐私政策](https://nitpik.dev/privacy)。
- **启用 `--scan-secrets`** 以在代码发送至 LLM 之前检测并隐去机密信息。这是一个尽力而为的安全网 —— 不寻常或自定义的机密格式可能无法被检测到。如果不使用此标志，diff 中存在的机密将被传输给提供商。
- **启用 `--scan-threats`** 以检测混淆的 payload、后门和其他恶意模式。这是一个尽力而为的防御层 —— 新型攻击技术或复杂的 payload 可能会逃避检测。威胁发现结果仅供参考 —— 请务必通过人工判断进行验证。
- **机密扫描和威胁扫描均无法保证检测出所有问题。** 请将它们与专用的安全工具、依赖审计和人工审查结合使用。
- **提供商集成依赖于第三方开源库。** LLM 提供商的支持可能会因 nitpik 无法控制的上游更新而发生改变、中断或被移除。如果您计划购买商业许可证，**请先使用免费的无许可证版本验证您的提供商和模型是否能正常工作。** 此操作无需许可证密钥 —— 只需安装并使用您自己的 API 密钥进行测试即可。
- nitpik 是一种开发辅助工具，不能替代人工代码审查、测试或安全审计。
## 遥测
nitpik 每次审查运行只会发送一个匿名的检测信号 —— **不包含任何代码、文件名、发现结果或 PII**。只包含汇总的计数（文件、行数、配置）以及您是否处于 CI 环境中。您可以通过阅读 [`src/telemetry/mod.rs`](src/telemetry/mod.rs) 来准确验证发送了什么内容。
检测信号 payload 仅包含：
- 随机的运行 ID（不跨运行保留）
- 文件数量和更改的总行数
- 使用的 agent 配置文件数量
- 是否激活了商业许可证
- 运行是否在 CI 环境中
- CLI 版本字符串
禁用遥测：
```
nitpik review --diff-base main --no-telemetry # per-run
export NITPIK_TELEMETRY=false # env var
```
```
# .nitpik.toml 或 ~/.config/nitpik/config.toml
[telemetry]
enabled = false
```
## 更新
nitpik 可以从 GitHub 自行更新至最新版本：
```
nitpik update # update to latest version (skips if already current)
nitpik update --force # re-download even if already on latest
```
更新过程会下载适用于您平台的发布归档文件，验证其 SHA256 checksum，并原子性地替换正在运行的二进制文件。
如果二进制文件安装在系统目录（例如 `/usr/local/bin`）中，您可能需要使用 `sudo`：
```
sudo nitpik update
```
## 版本信息
打印详细的构建元数据：
```
nitpik version
```
输出包含版本、git 提交记录、构建日期和目标三元组：
```
nitpik 0.2.0
commit: a1b2c3d
built: 2026-02-14
target: x86_64-unknown-linux-gnu
```
如需简短的单行输出，请使用标准的 `--version` 标志：
```
nitpik --version # nitpik 0.2.0
```
## 更多帮助
每个命令和标志都在内置帮助中进行了详细说明：
```
nitpik help # overview of all commands
nitpik help review # full review flag reference
nitpik help license # license management
nitpik help cache # cache management
nitpik help update # self-update
nitpik version # version, commit, build date, target
```
## 反馈与问题
发现了 bug、误报或有害的 AI 输出？请在 GitHub 上[创建一个 issue](https://github.com/nsrosenqvist/nitpik/issues)。您的反馈有助于为所有人改进 nitpik。
## 许可证
基于 [Business Source License 1.1](LICENSE) 授权。
**个人、教育和开源使用免费 —— 无需许可证密钥。** 商业用途需要许可证。支付单一固定费用，不限团队规模，不限使用量。请访问 [nitpik.dev](https://nitpik.dev) 了解定价。
您自带 LLM 提供商和 API 密钥 —— nitpik 绝不代理、存储或计量您的 API 调用。
每次发布三年后，代码将转换为 [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) 许可证。
[服务条款](https://nitpik.dev/terms) · [隐私政策](https://nitpik.dev/privacy)
手动设置（不使用 action）
``` on: pull_request jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/cache/restore@v4 with: path: ~/.config/nitpik/cache key: nitpik-${{ github.repository }} - name: Install nitpik run: curl -sSfL https://raw.githubusercontent.com/nsrosenqvist/nitpik/main/install.sh | bash - name: AI Code Review run: | nitpik review \ --diff-base "origin/$GITHUB_BASE_REF" \ --profile security,performance \ --format github \ --fail-on warning \ --scan-secrets env: NITPIK_PROVIDER: ${{ vars.NITPIK_PROVIDER }} NITPIK_MODEL: ${{ vars.NITPIK_MODEL }} NITPIK_API_KEY: ${{ secrets.NITPIK_API_KEY }} NITPIK_LICENSE_KEY: ${{ secrets.NITPIK_LICENSE_KEY }} - uses: actions/cache/save@v4 if: always() with: path: ~/.config/nitpik/cache key: nitpik-${{ github.repository }} ```标签：AI代码审查, DevSecOps, DNS 反向解析, LNA, SOC Prime, StruQ, URL收集, 上游代理, 可视化界面, 开发工具, 请求拦截, 通知系统