Overseer

🚀 Overseer

Overseer 是一個通過 MCP 實現 AI 代理任務編排的工具。它由 SQLite 提供支持，並使用原生版本控制系統（jj-lib + gix）。

🚀 快速開始

你可以通過以下方式安裝 Overseer：

📦 安裝指南

通過 npm 安裝

npm install -g @dmmulroy/overseer

通過 skills.sh 為代理安裝

npx skills add dmmulroy/overseer

💻 使用示例

MCP 服務器

將以下配置添加到你的 MCP 客戶端配置中：

{
  "mcpServers": {
    "overseer": {
      "command": "npx",
      "args": ["@dmmulroy/overseer", "mcp"]
    }
  }
}

命令行界面（CLI）

os task create -d "Implement auth"
os task list --ready
os task start <task-id>
os task complete <task-id>

🔧 技術細節

架構

┌─────────────────────────────────────┐
│     Overseer MCP (Node.js)          │
│  - Single "execute" tool (codemode) │
│  - VM sandbox with tasks/learnings  │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│         os CLI (Rust)               │
│  - SQLite storage                   │
│  - jj-lib (primary VCS)             │
│  - gix (git fallback)               │
└─────────────────────────────────────┘

代碼模式

使用單一的 execute 工具，代理編寫 JavaScript 代碼，服務器運行代碼：

const milestone = await tasks.create({
  description: "User auth system",
  context: "JWT + refresh tokens"
});

const login = await tasks.create({
  description: "Login endpoint",
  parentId: milestone.id
});

await tasks.start(login.id);  // VCS required: creates bookmark, records start commit
// ... do work ...
await tasks.complete(login.id, {  // VCS required: commits changes, bubbles learnings to parent
  result: "Implemented with bcrypt",
  learnings: ["bcrypt rounds should be 12+ for production"]
});

return { milestone, login };

任務層次結構

• 里程碑（深度 0） - 根任務，沒有父任務
• 任務（深度 1） - 父任務是里程碑
• 子任務（深度 2） - 最大深度，父任務是任務

API 文檔

tasks

tasks.create({ description, context?, parentId?, priority?, blockedBy? })
tasks.get(id)           // Returns TaskWithContext
tasks.list({ parentId?, ready?, completed?, depth?, type? })  // type: "milestone"|"task"|"subtask"
tasks.update(id, { description?, context?, priority?, parentId? })
tasks.start(id)
tasks.complete(id, { result?, learnings? })  // Learnings bubble to immediate parent
tasks.reopen(id)
tasks.delete(id)
tasks.block(taskId, blockerId)
tasks.unblock(taskId, blockerId)
tasks.nextReady(milestoneId?)
tasks.tree(rootId?)     // Returns TaskTree or TaskTree[] (all milestones if no ID)
tasks.search(query)     // Search by description/context/result
tasks.progress(rootId?) // Returns { total, completed, ready, blocked }

learnings

learnings.list(taskId)  // Learnings are added via tasks.complete()

版本控制系統（VCS，工作流必需）

VCS 操作集成到任務工作流中，沒有直接的 API：

VCS（jj 或 git）對於開始/完成任務 必需。CRUD 操作無需 VCS 也可工作。

漸進式上下文

任務從祖先繼承上下文。完成任務時，學習成果會冒泡到直接父任務（保留原始 sourceTaskId）：

const subtask = await tasks.get(subtaskId);
// subtask.context.own       - 此任務的上下文
// subtask.context.parent    - 父任務上下文（深度 > 0）
// subtask.context.milestone - 根里程碑上下文（深度 > 1）
// subtask.learnings.own     - 此任務的學習成果（完成子任務時添加）

CLI 參考

# 任務操作
os task create -d "description" [--context "..."] [--parent ID] [--priority 1-5]
os task get <id>
os task list [--parent ID] [--ready] [--completed]
os task update <id> [-d "..."] [--context "..."] [--priority N] [--parent ID]
os task start <id>
os task complete <id> [--result "..."] [--learning "..."]...
os task reopen <id>
os task delete <id>
os task block <id> --by <blocker-id>
os task unblock <id> --by <blocker-id>
os task next-ready [--milestone ID]
os task tree [ID]           # 無 ID 表示所有里程碑樹
os task search "query"
os task progress [ID]       # 彙總計數：總數、已完成、就緒、阻塞

# 學習成果（通過 task complete --learning 添加）
os learning list <task-id>

# VCS（僅 CLI - MCP 中自動處理）
os vcs detect
os vcs status
os vcs log [--limit N]
os vcs diff [BASE_REV]
os vcs commit -m "message"
os vcs cleanup [--delete]  # 列出/刪除孤立的任務分支

# 數據導出
os data export [-o file.json]

任務查看器

用於查看任務的 Web UI：

# 通過 CLI（安裝後）
os ui

# 或從倉庫（開發模式）
cd ui && npm install && npm run dev
# 打開 http://localhost:5173

有三種視圖：

• 圖形 - 帶有阻塞關係的有向無環圖可視化
• 列表 - 可過濾的任務列表
• 看板 - 按完成狀態展示的看板

鍵盤操作：g=圖形，l=列表，k=看板，?=幫助

開發

# Rust CLI
cd overseer && cargo build --release
cd overseer && cargo test

# Node MCP
cd mcp && npm install
cd mcp && npm run build
cd mcp && npm test

# UI（開發服務器）
cd ui && npm install && npm run dev

存儲

SQLite 數據庫位置（按優先級排序）：

1. OVERSEER_DB_PATH 環境變量（如果設置）
2. VCS_ROOT/.overseer/tasks.db（如果在 jj/git 倉庫中）
3. $CWD/.overseer/tasks.db（備用）

首次執行命令時自動創建。

VCS 檢測

1. 從當前工作目錄向上查找 .jj/ → 使用 jj-lib
2. 如果未找到，查找 .git/ → 使用 gix
3. 都未找到 → VcsType::None

優先使用 jj：有 jj 時總是優先使用。

📚 詳細文檔

• 架構 - 系統設計和不變量
• CLI 參考 - 完整的命令文檔
• MCP 指南 - 代理使用模式

📄 許可證

本項目採用 MIT 許可證。