内容
# djobs
<!-- mcp-name: io.github.jhuang-tw/djobs -->
**为 AI 编码代理节省令牌的持久化上下文**。djobs 为 Codex、Claude Code、Gemini、Copilot、Cursor、Cline 以及任何与 MCP 兼容的编码代理提供持久化、可恢复的任务内存——这样，长期、多文件的工作在崩溃、上下文丢失或会话中断时无需重放已完成的工作。 它包含 MCP 工具、代理指令和 VS Code 边栏；运行时自行安装和管理。
[](https://github.com/jhuang-tw/djobs/actions/workflows/ci.yml)
[](https://pypi.org/project/djobs/)
[](https://jhuang-tw.github.io/djobs/)
[](LICENSE)
[](https://www.python.org/downloads/)
<p align="center">
<img src="docs/demo.svg" alt="djobs demo — crash recovery in action" width="700">
</p>
---
## 问题
AI 编码代理（Codex、Claude Code、Gemini、GitHub Copilot、Cursor、Cline）通常运行多文件任务：为 40 个文件添加文档字符串、迁移框架版本、批量重构 API。这些任务可能需要几分钟。
当 IDE 崩溃、聊天断开或意外关闭窗口时，**所有正在进行的进度都会丢失**。代理的状态仅存在于聊天历史中。你需要花费令牌重新阅读、重新规划并猜测哪些文件已经完成。
## 解决方案
djobs 为您的代理提供了三种工具来解决这个问题：
| 工具 | 功能 |
|------|-------------|
| `enqueue_task` | 保存每个文件为持久化任务——在任何崩溃中都能存活 |
| `complete_task` | 在代理编辑文件后标记完成 |
| `resume_session` | 在下一次聊天时，立即找到所有未完成的任务 |
```
您：“为 src/ 目录下的所有 20 个文件添加文档字符串”
代理调用 enqueue_task 每个文件 ← 保存检查点
代理编辑文件 1 → complete_task ✅
代理编辑文件 2 → complete_task ✅
...
代理编辑文件 12 → complete_task ✅
💥 VS Code 崩溃
您重新打开 VS Code，开始新的聊天：“hi”
代理调用 resume_session ← 找到 8 个未完成的任务
代理编辑文件 13 → complete_task ✅
...
代理编辑文件 20 → complete_task ✅
完成 — 没有文件丢失，没有文件重复
```
所有内容都存储在本地 SQLite 文件中。无需 Redis、无需 Docker、无需云服务。
**在此仓库中测量：** `djobs token-savings` 估计在 20 个已完成的任务中避免了 12,136 个重放/重规划令牌（减少 82.6% 的上下文重放）。模型是明确且可复制的：`djobs token-savings --correlation-id <workspace> --format json`.
## 兼容性状态
当前实现和日常测试均在 **GitHub Copilot in VS Code** 上完成。djobs 基于 MCP 设计，因此它应该适用于任何与 MCP 兼容的编码代理主机，但非 Copilot 主机仍需要更广泛的实际验证。
| 代理/主机 | 状态 |
|--------------|--------|
| GitHub Copilot in VS Code | 已实现并通过 VS Code 扩展 + MCP 注册进行测试。 |
| Claude Code | 通过 `djobs init` / MCP 配置预期；尚未完全端到端测试。 |
| Cursor | 通过 `djobs init` / MCP 配置预期；尚未完全端到端测试。 |
| Cline | 通过 `djobs init` / MCP 配置预期；尚未完全端到端测试。 |
| Codex | 通过支持 MCP 的客户端使用时预期；尚未完全端到端测试。 |
| Gemini | 通过支持 MCP 的客户端使用时预期；尚未完全端到端测试。 |
| 普通浏览器聊天，无工具 | 非自动；djobs 需要 MCP/工具访问或安装的代理指导。 |
> **这与 Celery / RQ / Dramatiq 有何不同？** 它们是为后端工作者和高速吞吐量而构建的通用任务队列。djobs 专为 **AI 编码代理** 构建：它原生支持 MCP，针对崩溃恢复和人类可检查的审计轨迹进行优化，而不是原始吞吐量，并且在单个本地 SQLite 文件中运行，无需代理、无需守护进程。
> **这与代理内存/RAG 工具有什么不同？** 内存工具帮助代理 **回忆知识** —— 它们总结过去的会话（通常使用额外的 LLM 步骤），将摘要存储在向量数据库中，并在上下文中检索相关片段。djobs 跟踪 **工作状态**：哪些任务已完成，哪些任务仍在进行中，以及每个任务的证据记录。它检查并恢复而无需 **LLM 调用、无嵌入和后台服务** —— 只需一个本地 SQLite 文件 —— 因此恢复是精确且可审计的，而不是近似的。两者是互补的：一个帮助代理 **记住**，djobs 帮助它 **完成并证明** 工作。
> **成熟度 - 早期但已测试**。388 个测试通过，CI 覆盖 Python 3.11-3.13，SQLite 和可选的 PostgreSQL 后端。在公共 API 稳定之前标记为 Alpha；核心排队 → 完成 → 恢复流程稳定且每天都在使用。
---
## 快速开始
> **djobs 是您 AI 代理的工作流状态 - 而不是您应用程序的依赖项**。它适用于任何仓库（Python、JS、Go、Rust、文档），因为队列是代理使用的工具，而不是您的项目导入的库。djobs 安装和管理其自己的运行时；您只需选择如何设置它。
### 1. VS Code / GitHub Copilot（最简单）
从市场安装 **[djobs 扩展](https://marketplace.visualstudio.com/items?itemName=jhuang-tw.djobs)**，然后从命令面板运行 **`djobs: 设置/修复 djobs`**（或单击扩展提供的“设置 djobs”）。
此步骤安装运行时，连接 MCP 服务器，安装代理指令并添加任务侧栏。无需终端，无需手动配置。
设置后，您可以正常聊天 — “继续”、“修复此问题”、“运行测试”、“重试”、“上次运行失败”或“发布”就足够了。扩展程序不会生成、复制或打开聊天提示。它注册 MCP 工具，安装代理指导并显示持久性任务状态；代理决定何时调用 `resume_session`、排队多步骤工作并完成每个单元并提供证据。
### 2. 任意 MCP 代理（Codex、Claude Code、Gemini、Cursor、Cline、...）
单个命令为任意 MCP 兼容代理启用当前项目：
```bash
djobs init
```
它写入 `.vscode/mcp.json`，在 `.github/copilot-instructions.md` 中安装代理指导块，运行 `djobs doctor` 并打印下一步骤。它自动检测正确的解释器，因此即使在 JavaScript、Go 或 Rust 仓库中没有 Python 环境，线路也能正常工作。
> **djobs 不仅是 MCP 工具**。它还安装代理指令，以便编码代理主动调用 `resume_session`、`enqueue_task`、`complete_task` 和 `fail_task` 在长期或高风险工作中 - 您不必记住告诉它们。
<details>
<summary>安装 djobs 运行时（仅当设置询问时）</summary>
VS Code 扩展程序安装并修复运行时为您。如果您在 VS Code 外部设置，请全局安装一次 - 像 `git` 或 `ripgrep` 一样，而不是每个项目：
```bash
pipx install djobs # 隔离全局安装（推荐）
# 没有 pipx？ -> pip install djobs （或：python -m pip install --user djobs）
```
然后在任何项目中运行 `djobs init`。
</details>
### 粒度命令
`djobs init` 是推荐的路径，但每个步骤也可以单独使用：
```bash
djobs install-mcp # 只写入 .vscode/mcp.json
djobs install-instructions # 只写入代理指导块
djobs doctor # 诊断现有设置
```
在任何时候验证设置：
```bash
djobs doctor
# [OK ] djobs 包：v0.7.3 ...
# [OK ] 队列数据库（全局默认）：~/.djobs/global.db — 存在，可写入
# [OK ] mcp.json 连接：命令='djobs-mcp' — 已找到
# [OK ] 代理指导块：存在于 .github/copilot-instructions.md
```
<details>
<summary>选项和手动设置</summary>
```bash
# 一键设置并全自动批准（代理可以无需提示排队/完成/失败）
djobs init --full-approve
# 重新运行设置，覆盖现有的 mcp.json
djobs init --force
# 还写入 .agent.md （适用于读取它的代理）除了 copilot-instructions
djobs init --instructions-target all
# 仅连接，安全默认（只读工具自动批准）
djobs install-mcp
# 或连接并全自动批准
djobs install-mcp --full-approve
# 仅代理指导块（无 mcp.json 更改）
djobs install-instructions # -> .github/copilot-instructions.md
djobs install-instructions --target agent-md # -> .agent.md
djobs install-instructions --target all # -> 两者
djobs install-instructions --print # 打印块，不写入任何文件
```
或手动添加到 `.vscode/mcp.json`。全局安装后，`djobs-mcp` 控制台脚本在您的 PATH 上，因此每个 OS 上的连接方式都相同：
```json
{
"servers": {
"djobs": {
"type": "stdio",
"command": "djobs-mcp",
"autoApprove": [
"health", "resume_session", "check_task", "list_tasks", "audit_log"
]
}
}
}
```
<details>
<summary>每个项目的 venv（可移植，用于提交 mcp.json 的仓库）</summary>
如果您希望将 djobs 保留在每个项目的虚拟环境中 - 例如，以便 checked-in `mcp.json` 解析为每个协作者拥有的 `.venv` - 运行 `djobs install-mcp --portable` 以发出可移植的解释器提示：
```json
{
"servers": {
"djobs": {
"type": "stdio",
"command": "${workspaceFolder}/.venv/Scripts/python",
"args": ["-m", "djobs.mcp_server"],
"autoApprove": [
"health", "resume_session", "check_task", "list_tasks", "audit_log"
]
}
}
}
```
在 macOS / Linux 上，路径为 `${workspaceFolder}/.venv/bin/python`。您也可以使用 `djobs install-mcp --python /path/to/python` 显式固定解释器。
</details>
> **安全注意：** 默认 `autoApprove` 列表仅包括 **只读** 工具。如果您希望您的代理在没有确认提示的情况下排队/完成/失败任务，请将 `"enqueue_task"`、`"complete_task"` 和 `"fail_task"` 添加到数组中 - 但请理解这允许代理在不询问的情况下修改队列状态。
</details>
---
## 让您的代理自动使用 djobs
安装后，您的代理可以使用 MCP 工具 - 但除非您告诉它，否则它不会使用它们。在您的代理指令中添加以下内容（例如 `.github/copilot-instructions.md` 或任意 `.agent.md`）：
```
每个会话开始时，调用 resume_session 以查找未完成的任务。
对于多文件任务，为每个文件排队持久任务，并在每个编辑后调用 complete_task。
```
**这为您提供：**
- 每次新聊天时，自动显示未完成的任务
- 对于多文件任务（> 3 个文件），每个文件都作为持久任务跟踪
- 编辑每个文件后，记录进度
- 如果会话崩溃，下一个聊天会自动从停止的地方恢复 - 无需提问
您也可以使用 `djobs install-instructions` CLI 命令自动添加指导块。
---
## 看看它的实际操作
上面的动画 SVG 显示了完整的演示。要亲自运行：
```bash
pip install djobs
# 如果您克隆了仓库：
python examples/run_migration_demo.py
```
20 个文件排队 → 12 个完成 → 崩溃 → 恢复 → 8 个剩余完成。零数据丢失。
---
## 它还能做什么？
除了三个核心工具外，djobs 还提供：
- **`audit_log`** — “AI 昨天做了什么？”整个会话的完整事件历史记录。
- **`work_receipt`** — 基于证据的已完成任务回执：更改的文件、完成的任务及其证据、剩余的任务和推荐的下一步骤。当在 git 仓库中运行时，它还会结合 git 的真实信息 — git 实际看到的更改文件数量，以及任务声称但 git 显示没有待处理更改的文件 — 以便可以交叉检查声明和存储库。只读，因此下一个会话（或审查者）可以信任进度而无需重读聊天。CLI：`djobs receipt --correlation-id <workspace>` （添加 `--no-git` 以跳过 git 检查）。
- **`check_task` / `list_tasks`** — 检查单个任务或按工作区列出任务。
- **`health`** — 一目了然地查看队列状态。
- **`djobs doctor`** — 一次性设置检查：确认 djobs 已安装、队列数据库可写入且 `.vscode/mcp.json` 已正确连接。运行它（或 VS Code 中的“djobs：诊断设置”）以确保一切正常。
- **`djobs token-savings`** — 估算工作流避免的重放/重规划令牌数量。示例：`djobs token-savings --correlation-id C:\my\repo --format json`.
- **多代理协调** — 几个代理共享一个队列：`claim_task`（原子、独占）、`heartbeat_task`、`release_task`、任务依赖项（`depends_on`）、资源锁（`resource_key`）和代理注册表（`register_agent` / `agent_heartbeat` / `list_agents`）。
- **Web 仪表盘** — `djobs dashboard` 在 `http://127.0.0.1:8787` 上提供只读、跨代理的队列健康状况、每个任务和实时代理舰队的全局视图（仅限标准库，无额外依赖）。**仅限本地设计：** 无身份验证，绑定到 `127.0.0.1`；对于远程访问，请使用 SSH 隧道而不是公开公共接口。
- **重试和失败队列** — 失败的任务可以自动重试。
- **死信队列** — 耗尽所有重试次数的任务将被保留以供审查。
有关完整的架构、Python 库 API、PostgreSQL 后端、配置参考以及与其他工具的比较，请参阅 [docs/INTERNALS.md](docs/INTERNALS.md)。
---
## 开发
```bash
git clone https://github.com/jhuang-tw/djobs.git
cd djobs
python -m venv .venv && .venv/bin/activate
pip install -e ".[dev]"
pytest -q # 379 个测试（18 个因 Postgres 而跳过）
ruff check src/ tests/ # lint
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取指南。
---
## VS Code 扩展
djobs 包含用于可视化工作流控制的 VS Code 边栏扩展：
- **工作流仪表盘** — 按工作流和操作类型分组的任务，并带有进度指示器
- **原生 MCP 设置** — 在 VS Code 中注册 djobs MCP 服务器，无需手动配置
- **代理指导安装程序** — 教导兼容的代理恢复并创建持久的 djobs 任务，然后进行多步骤编辑
- **任务清理控件** — 右键单击任务以存档它、删除它、查看其审核历史记录、复制其 ID 或检查原始 JSON
- **暂停开关** — `djobs pause` / `djobs unpause`（或侧边栏暂停/恢复按钮）暂时停止代理恢复/排队时卡住的任务不会被删除
- **可选提示操作** — 默认情况下关闭；启用 `djobs.promptActions.enabled` 在聊天中显示用于完成工作流的提示操作
- **证据轨迹** — 查看代理在每个已完成的任务中实际更改的内容
从 `vscode-ext/` 安装 VSIX 或自行构建：
```bash
cd vscode-ext && npm install && npm run package
# 安装：code --install-extension djobs-X.Y.Z.vsix
```
---
## 路线图
- [x] 持久工作流状态（`enqueue` → `complete` → `resume`)
- [x] 审计轨迹 — “AI 做了什么？”
- [x] 带有 15 个工具的 MCP 服务器
- [x] `pip install djobs && djobs install-mcp` — 两步安装
- [x] 已发布到 PyPI
- [x] `complete_task` 证据字段 — 代理记录了更改内容
- [x] VS Code 侧边栏 — 工作流仪表盘、跳过/存档、检查证据
- [x] 代理指导安装程序 — 提示代理恢复/排队前创建持久的 djobs 任务
- [x] CLI 工作流控制 — `djobs skip`、`djobs accept-before`、`djobs archive-workflow`
- [x] 多代理协调 — 共享队列声明、依赖项、资源锁、代理注册表
- [x] Web 仪表盘 — `djobs dashboard` 跨代理全局视图
- [x] 发布到 VS Code Marketplace
- [ ] 状态栏徽章 + 通知警报
---
## 许可证
[MIT](LICENSE)
