Oboe MCP

面向编码代理的结构化逐一（one-by-one）工作流。

用于持久化逐一审查工作流的 MCP 服务器，为编码代理提供具有优先级的会话状态。

提供 16 种工具，用于在优先级评分的会话文件中创建、导航和解决项目，包括阻塞项目处理、一流的审批更新以及嵌套的子会话，因此 /obo 工作流可以使用 MCP 操作而不是原始的 JSON 编辑。

采用 AGPL-3.0-or-later 许可，并提供商业许可。 有关完整条款，请参阅 LICENSE。

PyPI 软件包

使用以下任一替代方案直接从 PyPI 安装或运行 Oboe MCP：

• 无需安装即可运行：uvx oboe-mcp

• 安装到当前环境：pip install oboe-mcp

安装 oboe-mcp 还会安装 oboe-cli 命令：

# After pip install oboe-mcp
oboe-cli --help

# From PyPI 
uvx --from oboe-mcp oboe-cli --help

# From a local checkout (no install needed)
uvx --from /path/to/oboe-mcp oboe-cli --help

CLI 参考 (oboe-cli)

安装 oboe-mcp 还会安装 oboe-cli，这是一个对人类友好的命令行伴侣，用于操作 MCP 工具所使用的相同会话文件。

oboe-cli [--session SESSION] [--base-dir DIR] COMMAND [ARGS...]

全局选项：

Base-dir 自动检测：当省略 --base-dir 时，oboe-cli 会使用当前工作目录（如果它包含 .github/obo_sessions/ 文件夹），否则它会回退到当前工作目录本身。

命令

快速入门

# Create a session from a JSON items file
oboe-cli --base-dir /path/to/project create \
    --title "Code review findings" \
    --input-file findings.json

# List sessions
oboe-cli --base-dir /path/to/project sessions

# Work through items
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json next
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
    in-progress 1
oboe-cli --base-dir /path/to/project --session session_20260411_120000.json \
    complete 1 "Fixed the validation bug"

注意：以前版本中附带的 obo_helper.py 脚本现在是一个精简的弃用垫片，它委托给 oboe-cli。

为什么选择 OBO 会话

逐一（One-By-One）会话不仅仅是保存的聊天记录。它们是一种工作流模型，用于将多项工作作为持久、有序的交互会话来处理。

与简单的聊天或代理内置的后续问题相比，OBO 增加了这些较轻量级交互模式通常不具备的功能：

• 以概览为先的工作流，代理可以从范围、项目计数、主要类别和建议的执行顺序开始

• 基于紧迫性、重要性、工作量和依赖压力的显式重新优先级排序，而不是聊天中出现的任何顺序

• 通过 pending（待处理）、in_progress（进行中）、deferred（延迟）、blocked（阻塞）、completed（已完成）和 skipped（已跳过）实现持久的生命周期状态

• 通过 approval_status、approval_mode、approved_at 和 approval_note 实现单独的审批元数据

• 存储阻塞者元数据，以便阻塞的工作仍然可见且可解释，而不是从活动队列中静默消失

• 嵌套的子会话，可以暂停父会话，处理子问题，然后干净地恢复父会话

• 一流的会话生命周期管理：作为命名工作流对象列出、创建、检查、合并、暂停、恢复和关闭会话

• 模型重启、编辑器重新加载或代理移交后的确定性恢复

• 会话文件中的机器可读审计跟踪，而不是依赖对话记忆

当工作跨越许多发现、需要明确的用户审批、依赖中间的子调查或必须在多个代理轮次中存续时，这一点最为重要。聊天擅长对话。结构化问题工具擅长在当前轮次中获得清晰的答案。OBO 用于持久的工作流编排。

当您需要受控的顺序处理、持久的队列状态或嵌套的子工作时，请使用 OBO。当任务足够小，以至于完整的工作流对象会增加比价值更多的开销时，请使用简单的聊天。

状态模型

OBO 在两个独立的轴上跟踪每个项目。

生命周期轴

• pending：工作已排队但尚未开始

• in_progress：工作目前正在积极进行中

• deferred：工作已批准稍后执行，在活动审查通过耗尽或用户明确请求延迟工作之前，应保持在立即审查队列之外

• blocked：在外部依赖或子问题解决之前，工作无法继续

• completed：工作已完成并关闭

• skipped：工作被有意不执行

审批轴

• unreviewed：尚未记录明确的用户决定

• approved：用户已授权该工作

• denied：用户已明确拒绝该工作

审批元数据字段：

• approval_status：项目的审批决定

• approval_mode：记录审批时间决定时为 immediate（立即）或 delayed（延迟）

• approved_at：记录审批的时间戳

• approval_note：关于审批决定的可选自由文本注释

常见配对：

• 立即批准：调用 obo_set_approval(..., approval_status="approved", approval_mode="immediate")；项目通常保持 pending，直到工作开始或被移动到 in_progress

• 延迟批准：调用 obo_set_approval(..., approval_status="approved", approval_mode="delayed")；这会记录延迟批准并将项目移动到 deferred

• 拒绝：设置 approval_status=denied；如果项目要从队列中关闭，请将其与 status=skipped 配对

交互模式

三种常见的交互模式是简单聊天、结构化问题工具和完整的 OBO 会话。它们解决不同的问题。

示例演变：

• 标准聊天：代理在散文中列出几个发现，对话本身成为处理内容的唯一记录。

• askQuestions：代理可以要求进行清晰的菜单选择，但除非它在其他地方存储，否则仍然没有持久的项目队列。

• OBO 会话：代理从概览开始，存储完整的项目列表，有意地对其进行排序，记录批准、跳过和阻塞者，并且可以在以后恢复，而无需从聊天历史记录中重建会话。

玩具示例：五个审查项目

假设代理审查一个小型待办事项应用程序，并按此原始发现顺序找到五个项目：

1. 改进 UI 中模棱两可的设置标签。

2. 解决后台同步作业中的竞态条件。

3. 为重复的任务 ID 添加回归测试。

4. 在创建任务端点上添加缺失的输入验证。

5. 修复登录处理程序中的密码记录。

标准聊天

代理：

我在玩具应用中发现了五个问题： 问题 1：改进 UI 中模棱两可的设置标签。 问题 2：解决后台同步作业中的竞态条件。 问题 3：为重复的任务 ID 添加回归测试。 问题 4：在创建任务端点上添加缺失的输入验证。 问题 5：修复登录处理程序中的密码记录。

你接下来想做什么？

用户：

先做 4 和 2。

评论：

• 这很快，但聊天本身成为序列的唯一记录，项目 4 和 3 之间的依赖关系是隐含的。

• 其他问题的状态没有被捕获，用户将需要明确要求代理显示或处理其他问题。

• 如果会话中断，另一个代理将不得不从转录中重建状态。

askQuestions 风格聊天

代理：

我发现了五个问题。我们应该先做哪一个？

选项： • 4. 在创建任务端点上添加缺失的输入验证 • 2. 解决后台同步作业中的竞态条件 • 5. 修复登录处理程序中的密码记录 • 3. 为重复的任务 ID 添加回归测试 • 1. 改进 UI 中模棱两可的设置标签

用户：

4

代理：

下一个动作？

选项： • 继续做 2 • 重新排序剩余列表 • 停止

评论：

• 这比简单聊天提供了更清晰的用户选择，但工具本身仍然没有创建一个持久的、感知依赖的工作流对象。

• 其他问题的状态仍然没有被捕获，用户将需要明确要求代理显示或处理其他问题。

• 同样，如果会话中断，另一个代理将不得不从转录中重建状态。

逐一（One-By-One）会话

遵循 OBO 代理提示说明，代理分配此排序逻辑：

• 项目 4 排在第一位，因为在编写后续回归测试之前，应稳定创建任务端点的行为。

• 项目 2 排在第二位，因为竞态条件会影响整个同步流程的正确性，并且可能需要嵌套的调查会话。

• 项目 5 紧随其后，因为它是一个重要的安全修复，但它不会阻塞验证和并发工作。

• 项目 3 排在项目 4 之后，因为回归测试应该锁定最终的验证行为，而不是在它之前。

• 项目 1 仍然有用，但与其他四个项目相比影响较小，所以它排在最后。

代理：

我为 5 个发现创建了一个 OBO 会话。

执行摘要： • 总项目：5 • 类别：1 API 正确性，1 并发，1 安全性，1 测试，1 UX • 优先级顺序：4, 2, 5, 3, 1 • 估计工作量：11 • 关键项目：3 • 依赖说明：项目 3 跟随项目 4，因此回归测试针对的是稳定的端点行为 • 子会话说明：项目 2 可能会分支到一个嵌套的调查会话中 • 当前会话状态：5 待处理，0 进行中，0 已完成

当前项目： • 项目 4 • 标题：在创建任务端点上添加缺失的输入验证 • 类别：API 正确性 • 优先级分数：18 • 基本原理：在处理后续回归测试之前稳定端点契约

回复以下选项之一： • 立即批准 • 延迟批准 • 拒绝 • 下一个 • 更多选项

用户：

立即批准

[ ... 代理在此处执行项目 4 的工作 ... ]

代理：

项目 4 已完成。

会话状态： • 1 已完成 • 4 待处理 • 20% 已完成

当前项目： • 项目 2 • 标题：解决后台同步作业中的竞态条件 • 类别：并发 • 优先级分数：15 • 基本原理：这会影响整个同步流程的正确性，并且在父项目可以解决之前可能需要嵌套调查

子会话说明： • 如果您批准立即执行，我将展示嵌套流程

回复以下选项之一： • 立即批准 • 延迟批准 • 拒绝 • 下一个 • 更多选项

用户：

立即批准。

代理：

项目 2 在我完成它之前需要隔离调查。我