Nightshift

它能找到你忘了寻找的东西。

nightshift.haplab.com · 文档 · 快速开始 · CLI 参考

你的 tokens 每周都会重置，不用白不用。Nightshift 会在夜间运行，找出死代码、文档漂移、测试缺口、安全问题以及其他 20 多类在功能开发过程中悄然积累的问题。就像你代码库的 Roomba——夜间运行，最坏情况也就是你关掉 PR。

所有内容都会以分支或 PR 的形式呈现。它永远不会直接写入你的主分支。不喜欢某个改动？关掉它就行。这就是完整的回滚方案。

功能特点

• 预算感知：使用剩余的每日配额，从不超过可配置的最大值（默认 75%）
• 多项目支持：指向你的仓库，它就知道要找什么
• 零风险：一切都以 PR 形式呈现——合并让你惊喜的，关掉其余的
• 优秀的开发者体验：精心设计的 CLI 默认值，输出清晰，有详细报告

安装

完整指南：安装文档

brew install marcus/tap/nightshift

二进制下载可在 GitHub releases 页面获取。

手动安装：

go install github.com/marcus/nightshift/cmd/nightshift@latest

快速开始

完整指南：快速开始文档

安装后，运行引导式设置：

nightshift setup

这将引导你完成提供商配置、项目选择、预算校准和守护进程设置。完成后可以预览 nightshift 将要执行的操作：

nightshift preview
nightshift budget

或者立即开始运行：

nightshift run

常用 CLI 用法

完整参考：CLI 参考文档

# 预览下次计划运行，带提示预览
nightshift preview -n 3
nightshift preview --long
nightshift preview --explain
nightshift preview --plain
nightshift preview --json
nightshift preview --write ./nightshift-prompts

# 引导式全局设置
nightshift setup

# 检查环境和配置健康状态
nightshift doctor

# 预算状态和校准
nightshift budget --provider claude
nightshift budget snapshot --local-only
nightshift budget history -n 10
nightshift budget calibrate

# 浏览和检查可用任务
nightshift task list
nightshift task list --category pr
nightshift task list --cost low --json

# 显示任务详情和规划提示
nightshift task show lint-fix
nightshift task show skill-groom
nightshift task show lint-fix --prompt-only

# 立即运行任务
nightshift task run lint-fix --provider claude
nightshift task run skill-groom --provider codex --dry-run
nightshift task show lint-fix --prompt-only

如果 gum 可用，预览输出会通过 gum 分页器显示。使用 --plain 可以禁用。

nightshift run

在执行前，nightshift run 会显示一个 飞行前摘要，展示所选的提供商、预算状态、项目和计划任务。在交互式终端中会提示确认；在非 TTY 环境（cron、守护进程、CI）中确认会自动跳过。

参数	默认值	描述
--dry-run	false	显示飞行前摘要并退出，不执行
--project, -p	(所有已配置的)	定位单个项目目录
--task, -t	(自动选择)	按名称运行特定任务
--max-projects	1	最大处理项目数（设置 --project 时忽略）
--max-tasks	1	每个项目的最大任务数（设置 --task 时忽略）
--random-task	false	从符合条件的任务中随机选择，而非得分最高的
--ignore-budget	false	绕过预算检查（谨慎使用）
--yes, -y	false	跳过确认提示

# 交互式运行，带飞行前摘要 + 确认提示
nightshift run

# 非交互式：跳过确认
nightshift run --yes

# 试运行：显示飞行前摘要并退出
nightshift run --dry-run

# 最多处理 3 个项目，每个 2 个任务
nightshift run --max-projects 3 --max-tasks 2

# 随机选择符合条件的任务
nightshift run --random-task

# 绕过预算限制（显示警告）
nightshift run --ignore-budget

# 直接定位特定项目和任务
nightshift run -p ./my-project -t lint-fix

其他有用参数：

• nightshift status --today 查看今日活动摘要
• nightshift daemon start --foreground 用于调试
• --category — 按类别过滤任务（pr, analysis, options, safe, map, emergency）
• --cost — 按成本层级过滤（low, medium, high, veryhigh）
• --prompt-only — 仅输出原始提示文本用于管道传输
• --provider — task run 必需，选择 claude 或 codex
• --dry-run — 预览提示而不执行
• --timeout — 执行超时时间（默认 30 分钟）

认证（订阅）

Nightshift 支持三个 AI 提供商：

• Claude Code - Anthropic 的 Claude，通过本地 CLI
• Codex - OpenAI 的 GPT，通过本地 CLI
• GitHub Copilot - GitHub 的 Copilot，通过 GitHub CLI

Claude Code

claude
/login

支持 Claude.ai 订阅或 Anthropic Console 凭据。

Codex

codex --login

支持使用 ChatGPT 或 API 密钥登录。

GitHub Copilot

# 安装 Copilot CLI
npm install -g @github/copilot
# 或
curl -fsSL https://gh.io/copilot-install | bash

需要 GitHub Copilot 订阅。详见 docs/COPILOT_INTEGRATION.md。

如果偏好基于 API 的使用方式，你可以用 API 密钥对 Claude 和 Codex CLI 进行认证。

配置

完整指南：配置文档 · 预算文档 · 调度文档 · 任务文档

Nightshift 使用 YAML 配置文件来定义：

• Token 预算限制（Token budget limits）
• 目标仓库（Target repositories）
• 任务优先级（Task priorities）
• 调度偏好（Schedule preferences）

运行 nightshift setup 创建/更新全局配置 ~/.config/nightshift/config.yaml。

详细选项请参阅完整配置文档或 SPEC.md。

最小配置示例：

schedule:
  cron: "0 2 * * *"

budget:
  mode: daily
  max_percent: 75
  reserve_percent: 5
  billing_mode: subscription
  calibrate_enabled: true
  snapshot_interval: 30m

providers:
  preference:
    - claude
    - codex
  claude:
    enabled: true
    data_path: "~/.claude"
    dangerously_skip_permissions: true
  codex:
    enabled: true
    data_path: "~/.codex"
    dangerously_bypass_approvals_and_sandbox: true

projects:
  - path: ~/code/sidecar
  - path: ~/code/td

任务选择：

tasks:
  enabled:
    - lint-fix
    - docs-backfill
    - bug-finder
  priorities:
    lint-fix: 1
    skill-groom: 2
    bug-finder: 2
  intervals:
    lint-fix: "24h"
    skill-groom: "168h"
    docs-backfill: "168h"

每个任务都有一个默认冷却间隔（cooldown interval），以防止同一任务在项目上运行过于频繁（例如 lint-fix 为 24h，docs-backfill 为 7 天）。可使用 tasks.intervals 按任务覆盖默认间隔。

skill-groom 默认启用。如果想选择退出，可将其添加到 tasks.disabled。它会使用 README.md 作为项目上下文来更新 .claude/skills 和 .codex/skills 下的项目本地技能，并从 https://agentskills.io/llms.txt 开始 Agent Skills 文档查询。

开发

Pre-commit 钩子

安装 git pre-commit 钩子以在推送前检查格式和代码问题：

make install-hooks

这会将 scripts/pre-commit.sh 符号链接到 .git/hooks/pre-commit。该钩子会运行：

• gofmt — 标记任何需要格式化的已暂存 .go 文件
• go vet — 捕获常见的正确性问题
• go build — 确保项目可以编译

如需临时绕过：git commit --no-verify

卸载

# 移除系统服务
nightshift uninstall

# 移除配置和数据（可选）
rm -rf ~/.config/nightshift ~/.local/share/nightshift

# 移除二进制文件
rm "$(which nightshift)"

许可证

MIT - 详见 LICENSE。

Nightshift 快速上手指南

Nightshift 是一款自动化代码库清理工具，能够在夜间运行，发现死代码、文档漂移、测试缺口、安全问题等 20+ 种代码质量问题。所有操作均以 PR 形式返回，不会直接写入主分支。

---

环境准备

系统要求

• 操作系统：macOS、Linux
• Shell：支持 Bash/Zsh

前置依赖

Nightshift 需要至少一种 AI provider：

提供商	安装方式
Claude Code	claude 命令行工具
Codex	codex 命令行工具
GitHub Copilot	@github/copilot npm 包

推荐安装 gum 以获得更好的交互式输出体验（可选）：

brew install gum

---

安装步骤

方式一：Homebrew（推荐）

brew install marcus/tap/nightshift

方式二：Go 安装

go install github.com/marcus/nightshift/cmd/nightshift@latest

确保 $GOPATH/bin 或 $HOME/go/bin 已加入 PATH。

方式三：二进制下载

访问 GitHub Releases 页面下载对应平台的二进制文件。

---

基本使用

1. 初始化配置

运行引导式设置，完成 provider 配置、项目选择、预算校准和守护进程设置：

nightshift setup

2. 预览运行计划

在正式运行前，可以预览 Nightshift 即将执行的操作：

nightshift preview

查看接下来 3 次计划运行：

nightshift preview -n 3

3. 检查预算状态

nightshift budget

查看特定 provider 的预算：

nightshift budget --provider claude

4. 执行扫描

确认预览结果后，运行扫描：

nightshift run

非交互式环境（cron、CI）自动跳过确认，或使用 --yes 跳过：

nightshift run --yes

5. 干运行模式

仅预览将要执行的任务，不实际运行：

nightshift run --dry-run

---

常用命令速查

# 查看可用的任务列表
nightshift task list

# 查看特定任务详情
nightshift task show lint-fix

# 运行指定任务
nightshift task run lint-fix --provider claude

# 检查环境配置健康状态
nightshift doctor

# 查看今日活动摘要
nightshift status --today

---

配置说明

配置文件位于 ~/.config/nightshift/config.yaml，首次运行 nightshift setup 时自动创建。

主要配置项：

budget:
  max_percent: 75          # 最大使用 75% 每日配额

providers:
  preference:
    - claude              # 优先使用 Claude

projects:
  - path: ~/code/your-project

tasks:
  enabled:
    - lint-fix
    - docs-backfill

---

卸载

# 移除系统服务
nightshift uninstall

# 移除配置和数据（可选）
rm -rf ~/.config/nightshift ~/.local/share/nightshift

# 移除二进制
rm "$(which nightshift)"