夜班

自动化研究辅助系统

![Status](https://github.com) ![Python](https://www.python.org/downloads/) ![License](LICENSE) ![Tests](https://github.com/james-alvey-42/nightshift/actions/workflows/test.yml) ![codecov](https://codecov.io/gh/james-alvey-42/nightshift) ![Slack](SLACK_QUICK_START.md)

*一个由人工智能驱动的科研自动化代理管理器，由Claude Code的无头模式和MCP工具提供支持。现在有了Slack集成！*

特性 • 安装 • 用法 • 文本用户界面 • Slack • 示例

______________________________________________________________________

概述

NightShift是一个工作原型，它在无头模式下使用Claude Code自动执行研究任务。该系统使用“任务规划器”代理来分析请求，选择适当的工具，并通过分阶段的审批工作流执行任务。

运作原理

graph TD
    A[User Request] --> B[Task Planner Agent]
    B --> C{Analyzes task
Selects MCP tools
Estimates resources}
    C --> D[Task Queue
STAGED]
    D --> E{User Approval}
    E --> F[Executor Agent
Claude headless]
    F --> G{Executes with tools
Tracks file changes}
    G --> H[Notification + Results]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style D fill:#ffe1f5
    style F fill:#fff4e1
    style H fill:#e1ffe1

项目结构

nightshift/
├── core/                        # Core system components
│   ├── agent_manager.py         # Orchestrates Claude headless processes
│   ├── task_planner.py          # Plans tasks using Claude
│   ├── task_queue.py            # SQLite-backed task queue
│   ├── logger.py                # Comprehensive logging
│   ├── file_tracker.py          # Monitors file changes
│   ├── notifier.py              # Task completion notifications (Terminal + Slack)
│   └── config.py                # Configuration management
├── integrations/                # Third-party integrations (NEW!)
│   ├── slack_client.py          # Slack API wrapper
│   ├── slack_handler.py         # Slack event routing
│   ├── slack_server.py          # Flask webhook server
│   ├── slack_formatter.py       # Block Kit message formatting
│   ├── slack_metadata.py        # Task metadata persistence
│   └── slack_middleware.py      # Request verification
├── interfaces/                  # User interfaces
│   ├── cli.py                   # Command-line interface
│   └── tui/                     # Interactive terminal UI
│       ├── app.py               # Application factory
│       ├── controllers.py       # Business logic layer
│       ├── widgets.py           # Custom prompt_toolkit controls
│       ├── keybindings.py       # Keyboard shortcuts
│       ├── layout.py            # UI layout composition
│       └── models.py            # Data structures
└── config/                      # Configuration files
    └── claude-code-tools-reference.md  # MCP tools reference

数据存储

所有NightShift数据都存储在 ~/.nightshift/:

~/.nightshift/
├── config/
│   └── slack_config.json       # Slack credentials (secure)
├── database/
│   └── nightshift.db           # Task queue database
├── logs/
│   └── nightshift_YYYYMMDD.log # Execution logs
├── output/
│   ├── task_XXX_output.json    # Task outputs
│   └── task_XXX_files.json     # File change tracking
├── notifications/
│   └── task_XXX_notification.json  # Completion summaries
└── slack_metadata/
    └── task_XXX_slack.json     # Slack context (channel, user, thread)

特性

✅ 已实施（第一阶段）

🧠 智能任务规划

Claude分析请求并选择合适的MCP工具

🔒 分阶段审批工作流

执行前审查任务（防止产生幻觉）

✏️ 计划修订

在执行之前请求对任务计划进行更改并提供反馈

🔧 MCP工具集成

利用ArXiv、Gemini、Claude、OpenAI和其他MCP服务器

📁 文件更改跟踪

监控在执行过程中创建/修改了哪些文件

👁️ 执行查看器

任务执行会话的美观、易读的显示

🔔 丰富的通知

详细的完成总结，包括文件更改

💻 CLI接口

用于任务管理的简单命令

🖥️ 交互式TUI

功能齐全的终端用户界面，带有类似vim的导航

💾 永久存储

SQLite数据库，集中式数据目录

📊 令牌和时间跟踪

监控每个任务的资源使用情况

🔄 过程控制

暂停、恢复和终止正在运行的任务

📱 Slack集成 ⭐ 新

提交任务，通过按钮批准，获取完成通知

🔀 并发任务执行 ⭐ 新

使用可配置的工作池同时执行多个任务

⏱️ 可配置超时

设置每个任务的执行时间限制（默认值：15分钟）

🔐 跨过程控制

从任何终端管理执行器服务

🚧 计划（第2+阶段）

📊 实时进度更新

在Slack执行时显示任务进度

🔄 通过Slack进行修订

通过模态对话框请求更改计划

📤 文件上传

将任务输出直接上传到Slack频道

👥 多用户授权

基于角色的访问控制（管理员/用户/查看器）

⚡ 后台处理

使用队列工作者执行完全异步任务

🛡️ 资源限制

自动终止失控任务、内存/CPU限制

🔍 RAG上下文感知

搜索文档和过去的任务

📚 知识库

从错误和更正中学习

💬 WhatsApp集成

移动任务管理

🎯 专业任务类型

- 数据分析工作流程 - 代码维护自动化 - 环境设置脚本

安装

cd nightshift
pip install -e .

这将安装所有必需的依赖项，包括：

克劳德代码CLI（通过克劳德代理SDK）
提示工具包（用于交互式TUI）
Slack SDK（用于Slack集成）
Flask（用于webhook服务器）
丰富（用于美观的终端输出）

可选： 对于Slack集成，您还需要：

Slack工作区和应用程序
Bot令牌和签名密钥（通过 nightshift slack-setup)
ngrok或类似的本地测试（见 SLACK_QUICK_START.md)

用法

快速开始

📝 Submit a task

# Submit and wait for approval
nightshift submit "Download and summarize arxiv paper 2510.13997 using Gemini"

# Auto-approve and execute immediately
nightshift submit "Download arxiv paper 2510.13997" --auto-approve

📋 View task queue

# View all tasks
nightshift queue

# Filter by status
nightshift queue --status staged
nightshift queue --status completed

✅ Approve and execute

nightshift approve task_3acf60c6

✏️ Revise a plan

# Request changes to a staged task plan
nightshift revise task_3acf60c6 "Use Claude instead of Gemini for summarization"

# Revise again with more feedback
nightshift revise task_3acf60c6 "Also save the summary as a PDF file"

📊 View results

# Basic info
nightshift results task_3acf60c6

# Show full output (raw JSON)
nightshift results task_3acf60c6 --show-output

👁️ Display execution (NEW!)

# View task execution in human-readable format
# Shows Claude's responses, tool calls, and results as they happened
nightshift display task_3acf60c6

此命令解析流json输出，并将其显示为实际的Claude会话：

💬 克劳德的信息和推理
🔧 带参数的工具调用
✅ 工具结果和错误
📊 代币使用和成本统计

非常适合调试和理解执行过程中发生的事情！

❌ Cancel a task

nightshift cancel task_3acf60c6

🗑️ Clear all data

# With confirmation
nightshift clear

# Skip confirmation
nightshift clear --confirm

⌨️ Shell Autocomplete (NEW!)

# Auto-detect shell and install completion
nightshift completion --install

# Show instructions for specific shell
nightshift completion --shell zsh
nightshift completion --shell bash
nightshift completion --shell fish

# Reload your shell
source ~/.zshrc  # or ~/.bashrc for bash

什么会自动完成：

✅ 命令： nightshift sub → nightshift submit
✅ 子命令： nightshift executor st → nightshift executor start
✅ 选项： nightshift queue --st → nightshift queue --status
✅ 状态值： nightshift queue --status → 显示所有状态选项
✅ 任务ID（动态）: nightshift approve task_ → 显示所有已执行的任务
✅ 上下文感知任务筛选：

- approve 和 revise → 仅限暂存任务 - cancel → 仅限于已搁置或已提交的任务 - pause, resume, kill → 仅运行或暂停任务 - results, display, watch → 所有任务

支持的壳： Bash（4.4+）、Zsh、Fish、PowerShell

这通过减少拼写错误和帮助发现可用命令，显著提高了CLI的可用性！

🔀 Concurrent Execution (NEW!)

# Start executor service (processes tasks in background)
nightshift executor start

# Start with custom settings
nightshift executor start --workers 5 --poll-interval 2.0

# Check executor status
nightshift executor status

# Stop executor service
nightshift executor stop

# Submit task with custom timeout (default: 900s / 15 minutes)
nightshift submit "Download paper" --timeout 300

# Submit and execute synchronously (wait for completion)
nightshift submit "Quick task" --auto-approve --sync

它是如何工作的：

执行者轮询队列 COMMITTED 任务并同时执行
配置最大workers（默认值：3）和轮询间隔（默认设置：1.0秒）
每个任务都有一个可配置的超时，以防止执行失控
任务可以同时从多个终端/Slack提交
可以使用PID文件跟踪从任何终端控制执行器

优点：

⚡ 多个任务并行执行
🔄 在其他任务运行时提交任务
🎯 无阻塞-提交并继续
🛡️ 超时可防止任务挂起

______________________________________________________________________

终端用户界面（TUI）

NightShift包括一个功能齐全的交互式终端界面，用于任务管理。

🖥️ Launch the TUI

nightshift tui

⌨️ Keybindings

关键	行动
`j` / `↓`	在任务列表中下移
`k` / `↑`	在任务列表中向上移动
`Enter` / `a`	批准所选任务
`r`	拒绝/取消任务
`e`	查看/编辑任务计划（打开$EDITOR）
`d`	删除任务
`Tab`	循环详细信息选项卡（概述/执行/文件/摘要）
`:`	进入命令模式
`q`	退出

命令模式(:):

:queue [status] -按状态筛选任务
:submit -提交新任务
:submit! -提交并自动批准
:refresh -刷新任务列表
:help -显示可用命令
:quit -退出TUI

______________________________________________________________________

Slack集成

NightShift可以完全通过Slack进行控制，允许您提交任务、用按钮批准任务并接收详细的完成通知——所有这些都不需要离开Slack！

快速开始

🚀 Setup (5 minutes)

创建Slack应用程序 （如果尚未完成）

- 首选https://api.slack.com/apps - 为您的工作区创建新应用程序 - 添加机器人令牌作用域： commands, chat:write, chat:write.public, files:write - 安装到工作区并复制Bot令牌

配置夜班

   nightshift slack-setup

按照提示输入您的机器人令牌和签名密钥。

启动服务器

   nightshift slack-server

暴露与ngrok （用于测试）

   ngrok http 5000

复制ngrok URL并更新您的Slack应用程序设置：

- Slash命令URL： https://YOUR-NGROK-URL/slack/commands - 交互URL： https://YOUR-NGROK-URL/slack/interactions

📖 完整指南： SLACK_QUICK_START.md

Slack命令

📝 Submit a task

/nightshift submit "download and summarize arxiv paper 2510.13997"

发生了什么：

🔄 即时响应：“规划任务…（30-120s）”
📋 通过按钮显示批准消息
✅ 点击“批准”→ 任务执行
📨 完成通知及结果

📋 View queue

/nightshift queue
/nightshift queue staged

显示所有任务或按状态筛选。

📊 Check status

/nightshift status task_abc123

显示当前状态、创建时间和输出路径。

🎛️ Process control

/nightshift pause task_abc123
/nightshift resume task_abc123
/nightshift kill task_abc123
/nightshift cancel task_abc123

控制正在运行和排队的任务。

交互式按钮

每条批准消息包括：

✅ 批准 -执行任务
❌ 拒绝 -取消任务
ℹ️ 详情 -查看完整任务详细信息（临时消息）

完工通知

当任务完成时，您将收到一个详细的通知，显示：

你要什么 -原始任务描述
NightShift发现/创建了什么 -Claude的实际响应（前1000个字符）
NightShift做了什么 -创建/修改/删除的文件列表
执行指标 -时间、令牌、状态
完整结果路径 -完整输出文件的链接

Slack工作流示例

You: /nightshift submit "fetch today's top 3 BBC headlines"

NightShift: 🔄 Planning task... This may take 30-120 seconds.

[30s later]

NightShift: 🎯 Task Plan: task_abc123

Description: Fetch today's main headlines from the BBC news website...

Tools: WebFetch
Estimated: ~800 tokens, ~20s

[✅ Approve] [❌ Reject] [ℹ️ Details]

You: *clicks ✅ Approve*

NightShift: ✅ Task task_abc123 approved by @you
⏳ Executing...

[20s later]

NightShift: ✅ Task SUCCESS: task_abc123

What you asked for:
Fetch today's top 3 BBC headlines

What NightShift found/created:
Here are today's top 3 BBC headlines:

1. Breaking: Major Political Development - Prime Minister announces...
2. International Crisis Update - Tensions rise as...
3. Technology Breakthrough - Scientists discover...

Status: SUCCESS
Execution Time: 21.5s
Tokens Used: 465

📄 Full results: ~/.nightshift/output/task_abc123_output.json

📖 完整文档： 测试_SLACK集成.md

______________________________________________________________________

示例工作流

📄 研究论文分析

$ nightshift submit "Download arxiv paper 2510.13997 and summarize using Gemini"

Planning task...
✓ Task created: task_3acf60c6

╭─────────────────────────────── Task Plan ───────────────────────────────╮
│ Tools needed: mcp__arxiv__download, Read, mcp__gemini__ask, Write       │
│ Estimated: ~3500 tokens, ~90s                                           │
╰─────────────────────────────────────────────────────────────────────────╯

⏸  Status: STAGED (waiting for approval)
Run 'nightshift approve task_3acf60c6' to execute
Or 'nightshift revise task_3acf60c6 "feedback"' to request changes

$ nightshift approve task_3acf60c6

✓ Task approved: task_3acf60c6
▶ Executing...

[... execution logs ...]

✓ Task completed successfully!
Token usage: 3017
Execution time: 122.9s

════════════════════════════════════════════════════════════════════════════
## ✅ Task Completed: task_3acf60c6

**Description:** Download the ArXiv paper with ID 2510.13997...
**Status:** SUCCESS
**Execution Time:** 122.9s
**Token Usage:** 3017

### File Changes
**Created (2):**
- ✨ 2510.13997.pdf
- ✨ arxiv_2510.13997_summary.md

**Results:** output/task_3acf60c6_output.json
════════════════════════════════════════════════════════════════════════════

🔧 代码库管理

$ nightshift submit "Download the mcp-handley-lab repository from the handley-lab GitHub organization and create a pull request addressing issue #50"

Planning task...
✓ Task created: task_7d2a1f9b

╭─────────────────────────────── Task Plan ───────────────────────────────╮
│ Tools needed: Bash, Read, Write, Edit, Glob, Grep                       │
│ Estimated: ~2000 tokens, ~120s                                          │
│ Reasoning: Clone repo, analyze issue, implement fix, create PR          │
╰─────────────────────────────────────────────────────────────────────────╯

⏸  Status: STAGED (waiting for approval)
Run 'nightshift approve task_7d2a1f9b' to execute

$ nightshift approve task_7d2a1f9b

✓ Task approved: task_7d2a1f9b
▶ Executing...

[... cloning repository ...]
[... analyzing issue #50 ...]
[... implementing fix ...]
[... creating pull request ...]

✓ Task completed successfully!
Token usage: 1847
Execution time: 98.3s

════════════════════════════════════════════════════════════════════════════
## ✅ Task Completed: task_7d2a1f9b

**Description:** Download the mcp-handley-lab repository...
**Status:** SUCCESS
**Execution Time:** 98.3s
**Token Usage:** 1847

### File Changes
**Created (1):**
- ✨ mcp-handley-lab/ (repository directory)

**Modified (3):**
- 📝 mcp-handley-lab/src/fix_file.py
- 📝 mcp-handley-lab/tests/test_fix.py
- 📝 mcp-handley-lab/README.md

**Pull Request:** https://github.com/handley-lab/mcp-handley-lab/pull/123
════════════════════════════════════════════════════════════════════════════

✏️ 计划修订工作流程

$ nightshift submit "Analyze the latest trends in quantum computing"

Planning task...
✓ Task created: task_9b4e2c1a

╭─────────────────────────────── Task Plan ───────────────────────────────╮
│ Enhanced prompt: Search for and analyze recent quantum computing papers │
│ Tools needed: WebSearch, Write                                          │
│ Estimated: ~1500 tokens, ~60s                                           │
│ Reasoning: Use web search to find trends, compile analysis              │
╰─────────────────────────────────────────────────────────────────────────╯

⏸  Status: STAGED (waiting for approval)
Run 'nightshift approve task_9b4e2c1a' to execute
Or 'nightshift revise task_9b4e2c1a "feedback"' to request changes

$ nightshift revise task_9b4e2c1a "Focus on arxiv papers from 2024, not web search"

Revising plan based on feedback...
✓ Plan revised: task_9b4e2c1a

╭─────────────────────────────── Revised Plan ────────────────────────────╮
│ Revised prompt: Search arxiv for quantum computing papers from 2024... │
│ Tools needed: mcp__arxiv__search, Read, mcp__gemini__ask, Write        │
│ Estimated: ~2500 tokens, ~120s                                          │
│ Changes: Switched from WebSearch to ArXiv tools, added Gemini for      │
│          analysis, increased time estimate for paper processing         │
╰─────────────────────────────────────────────────────────────────────────╯

Status: STAGED (waiting for approval)
Run 'nightshift approve task_9b4e2c1a' to execute
Or 'nightshift revise task_9b4e2c1a "more feedback"' to revise again

$ nightshift approve task_9b4e2c1a

✓ Task approved: task_9b4e2c1a
▶ Executing...

[... execution with revised plan ...]

✓ Task completed successfully!

______________________________________________________________________

开发说明

技术细节

核心架构

🎯 任务计划器使用 claude -p 随着 --json-schema 确保结构化输出
⚙️ 执行者使用 claude -p 随着 --verbose --output-format stream-json
📸 文件跟踪在执行之前/之后拍摄快照
⏱️ 每个任务可配置超时（默认值：900秒/15分钟）
🔌 所有Claude调用都是子流程执行（无SDK）
🔀 用于并发任务执行的ThreadPoolExecutor（不是ProcessPoolExecutors，因为Claude CLI已经生成了子进程）
🗄️ SQLite WAL模式用于并发数据库访问
🔒 原子任务获取 BEGIN IMMEDIATE 防止种族状况
📝 用于跨进程执行器控制的PID文件跟踪

Slack集成

🔐 所有webhook请求的HMAC-SHA256签名验证
⏰ 基于时间戳的重放攻击防御（5分钟窗口）
🚦 速率限制：命令为10/min，交互为20/min
🧵 异步规划和执行的线程支持
💾 用于跟踪Slack上下文（频道、用户、线程）的元数据持久性
📦 用于丰富交互式消息的块工具包格式

安全

凭据存储在 ~/.nightshift/config/ （从不使用git）
请求正文缓存以进行签名验证
DM信道检测（使用user_id而不是channel_id）
根据用户反馈进行优雅的错误处理

______________________________________________________________________

使用克劳德代码构建 • 由MCP供电

由...制作❤️ 面向研究人员和开发人员

nightshift (James Alvey 42)

快速接入

详细介绍

夜班

概述

运作原理

项目结构

数据存储

特性

✅ 已实施（第一阶段）

🚧 计划（第2+阶段）

安装

用法

快速开始

终端用户界面（TUI）

Slack集成

快速开始

Slack命令

交互式按钮

完工通知

Slack工作流示例

示例工作流

📄 研究论文分析

🔧 代码库管理

✏️ 计划修订工作流程

开发说明

核心架构

Slack集成

安全

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP