overseer (Dmmulroy)

⚠️ 存档： 该项目已不再积极维护。我已经转向其他工具和工作流程。请随意分叉和使用这个项目，只要你认为合适！

监督者

通过MCP为AI代理进行任务编排。SQLite支持的本地VCS（jj-lib+gix）。

安装

通过npm

npm install -g @dmmulroy/overseer

通过skills.sh（代理）

npx skills add dmmulroy/overseer

用法

MCP 服务器

添加到MCP客户端配置中：

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

命令行界面

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

建筑

┌─────────────────────────────────────┐
│     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 工具-代理编写JS，服务器运行它：

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）-最大深度，父级为任务

应用程序编程接口

任务

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.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       - This task's context
// subtask.context.parent    - Parent task context (depth > 0)
// subtask.context.milestone - Root milestone context (depth > 1)
// subtask.learnings.own     - This task's learnings (added when completing children)

CLI参考

# Tasks
os task create -d "description" [--context "..."] [--parent ID] [--priority 1-5]
os task get 
os task list [--parent ID] [--ready] [--completed]
os task update  [-d "..."] [--context "..."] [--priority N] [--parent ID]
os task start 
os task complete  [--result "..."] [--learning "..."]...
os task reopen 
os task delete 
os task block  --by 
os task unblock  --by 
os task next-ready [--milestone ID]
os task tree [ID]           # No ID = all milestone trees
os task search "query"
os task progress [ID]       # Aggregate counts: total, completed, ready, blocked

# Learnings (added via task complete --learning)
os learning list 

# VCS (CLI only - automatic in 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]  # List/delete orphaned task branches

# Data
os data export [-o file.json]

任务查看器

用于查看任务的Web UI：

# Via CLI (after installing)
os ui

# Or from repo (development)
cd ui && npm install && npm run dev
# Opens http://localhost:5173

三种观点：

• 图 -具有阻塞关系的DAG可视化
• 列表 -可筛选任务列表
• 看板 -按完成状态列出的董事会

键盘： 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 (dev server)
cd ui && npm install && npm run dev

存储

SQLite数据库位置（按优先级顺序）：

1. OVERSEER_DB_PATH env var（如果已设置）
2. VCS_ROOT/.overseer/tasks.db （如果在jj/git仓库中）
3. $CWD/.overseer/tasks.db （回退）

在第一个命令时自动创建。

VCS检测

1. 从cwd向上走，寻找 .jj/ → 使用jj库
2. 如果未找到，请查找 .git/ → 使用gix
3. 两者都不→ Vcs类型：：无

jj优先：有空的时候总是更喜欢jj。

文档

• 建筑 -系统设计，不变量
• CLI参考 -完整的命令文档
• MCP指南 -代理使用模式

许可证

麻省理工学院