CodePlus

中文 | English

探索任务之间如何直接通信、交接并长期协作，同时提供一个真正可用的终端 AI 编程工具。

CodePlus 并不是为了直接复刻 Codex。我希望通过这个项目持续探索新的 Agent 协作方式，同时吸收现有工具中已经得到验证的优秀实践，并逐步把自己的理解变成可以公开、可以使用的技术实现。

我看到很多人分享自己的 Agent 工作流，其中不少都会使用多个子 Agent。但真正利用“任务与任务之间直接通信”这一能力的工作流，似乎并不多见或者说还未见到。

Codex 并没有特别明显地宣传这个能力，至少我最初没有看到相关介绍。我是在一次偶然的交互中发现它的：我让一个任务为另一个任务准备提示词，原本以为它会把提示词发给我复制，结果它直接把消息发送给了目标任务。当时我甚至不知道任务之间可以这样通信。

后来我开始尝试把它用于不同场景：

• 任务交接：任务 A 完成后，创建一个拥有全新上下文的任务，并把整理后的交接信息直接发送给它。
• 模型分工：创建使用不同模型或推理能力的任务，只把适合其能力和成本的工作交给它们。
• 进度监控：让一个任务定期用自然语言总结另一个任务的进展，并判断是否需要人工调整；需要调整时，可以直接把纠偏指令发送给实现任务。
• 多层编排：由总控任务创建多个独立任务，独立任务在完成或遇到阻塞时主动汇报；每个任务内部还可以继续使用子 Agent 拆分局部工作。
• 高可见度的并行协作：把原本隐藏在单个 Agent 内部的执行过程，变成用户可以观察、打开、介入、停止和重新连接的独立任务。

这还不是全部。任务可以归档不再需要的会话、提前创建并等待触发条件、在空闲后被再次唤醒，也可以同时接收统一的新指令。一个任务甚至可以先确认自己理解了工作，然后保持等待，直到另一个任务在条件满足时只发送一句“开始”。

CodePlus 也是围绕这种工作方式构建的：让多个任务不再是互相隔离的一次性对话，而是能够持续通信、交接、等待、恢复和协同的工作单元。

用户可见任务和内部子 Agent 解决的是不同问题，不应该混为一谈。

用户可见任务                         当前任务内部

任务 A      任务 B      任务 C       当前任务
  │           │           │             └── 子 Agent
  └──── 消息、等待、交接 ──┘                  └── 子 Agent

独立窗口、独立上下文、可重新附着       局部研究、审查和有界并行

用户可见任务适合长期存在、跨任务通信和人工介入。内部子 Agent 更适合在当前任务内部完成代码审查、局部研究或并行修改。CodePlus 同时保留这两种模型，并让用户明确知道自己正在使用哪一种。

下面这些名称来自我当前使用 Codex Desktop 时观察到的工具环境。它们用于说明 CodePlus 的灵感来源和能力映射，不代表 OpenAI 对这些内部工具名称或行为作出的长期兼容承诺；不同版本、账户和运行环境中可见的能力也可能不同。

一个典型流程是：

create_thread
    -> send_message_to_thread
    -> wait_threads
    -> read_thread

这里有三个关键区别：

1. create_thread 创建的是用户能够在侧边栏看到和打开的独立任务。
2. send_message_to_thread 是跨任务发送后续信息，不是把提示词复制回当前对话。
3. wait_threads 等待的是状态事件，不需要反复读取其他任务的完整历史。

任务完成后，目标任务还可以主动通过 send_message_to_thread 向来源任务汇报结果或阻塞原因。

内部子 Agent 通常不作为平级任务出现在用户任务列表中，适合有边界、可并行的局部工作。用户可见任务则更接近独立工作线程：它们拥有自己的生命周期，可以被单独打开、等待和继续发送消息。

它们组成最常见的工程闭环：

读取代码 -> 修改代码 -> 构建或测试 -> 检查真实输出

这些工具管理目标、计划和上下文，本身不替代真实的代码执行工具。

CodePlus 没有停留在概念或界面演示。下面这些能力已经接入真实的 Service、持久化状态和执行入口。

Runtime Task 还提供完整 CLI 入口：

codeplus task spawn
codeplus task new
codeplus task open
codeplus task respond
codeplus task send
codeplus task wait
codeplus task read
codeplus task list
codeplus task fork
codeplus task interrupt
codeplus task resume
codeplus task delete

• 每个用户可见任务都可以拥有完整 Textual TUI，而不是只显示 worker 日志的预览窗口。
• 多个窗口可以附着到同一个持久化任务；关闭客户端不会自动停止后台 runner。
• 窗口支持继续输入、流式输出、工具调用展示、权限选择、AskUser、任务切换和重新附着。
• 新消息在任务等待用户授权时仍会可靠排队，权限卡片保持可操作；用户回复后任务自动继续处理后续消息。

• 任务、消息、事件、Turn 和交互请求持久化到 SQLite WAL。
• 每个任务只有一个 runner 写入 Session，客户端与 runner 生命周期分离。
• 消息使用 FIFO、租约、心跳、CAS 和幂等键，避免并发窗口重复执行同一轮。
• 完成 Turn 与输入消息建立持久化关联，进程恢复时不会因为确认阶段崩溃而简单重放已完成 Turn。
• 权限和 AskUser 响应采用首次响应胜出的 CAS 语义，多个窗口不会重复提交决定。
• 同一任务树的全局活跃 Turn 上限为 8，超过限制的 Turn 保持持久化排队。

• Git 项目可以为任务创建隔离 worktree；非 Git 项目使用共享目录。
• 首次写入前可以让用户选择共享目录或隔离工作区，选择结果持久化到任务状态。
• 支持 default、acceptEdits和 bypassPermissions 权限模式。
• 权限规则可按用户、项目和本地覆盖层加载，并结合路径沙箱和危险命令检测。
• 后台任务不会因为没有窗口就自动批准待处理权限。

• Agent 用于当前任务内部的有界子 Agent 工作。
• TeamCreate、TeamDelete、SendMessage、TaskCreate、TaskGet、TaskList、TaskUpdate 和 TaskStop 提供内部团队与共享工作项协调。
• 用户可见 Runtime Task 与内部 Agent/Team 使用不同入口，避免把内部执行单元错误展示成平级任务。

• 本地工具：ReadFile、WriteFile、EditFile、Bash、Glob、Grep。
• 交互工具：AskUserQuestion、EnterWorktree、ExitWorktree；Plan 由独立 collaboration mode 控制。
• Skill：安装、加载、嵌套选择和运行时执行。
• MCP：支持 stdio、Streamable HTTP 和 SSE 服务，动态注册远程工具。
• 模型：支持 Anthropic、OpenAI 和 OpenAI 兼容协议的 Provider 配置；每个 Runtime Task 都可以选择并持久化自己的 Provider，也可以在轮次边界切换。
• 上下文：Session 历史、自动 Memory、项目指令、上下文压缩、文件历史和 rewind。
• 扩展：生命周期 Hooks、工具搜索、权限规则和非交互 stream-json 输出。

CodePlus 借鉴了我在 Codex 中观察到的任务协作方式，但不会逐项复制某个现有产品。以下能力仍属于后续探索方向：

• 用户可见任务的固定、软归档和独立标题管理。
• 跨项目、跨 worktree 或跨执行环境的异步 handoff 及状态查询。
• Codex Desktop 项目目录发现和桌面终端缓冲区读取。
• 定时任务、提醒、周期监控和条件触发唤醒。
• 让主任务根据工作类型，自动为不同任务选择已经配置好的 Provider、模型与 API Key。目前每个任务已经可以手动选择独立 Provider，而每个 Provider 可以配置自己的模型和密钥；尚未完成的是由主任务自主决策和动态路由。
• 由主任务自主分配总预算，根据任务难度规划推理强度和成本份额，并持续识别执行偏差、及时纠偏。
• 识别任务上下文与原始目标之间的偏离，在不打断正常执行的前提下请求澄清、重新规划或交接。

flowchart LR
    User[用户]
    TuiA[Task TUI A]
    TuiB[Task TUI B]
    Service[RuntimeTaskService]
    Database[(SQLite WAL Coordinator)]
    RunnerA[Task Runner A]
    RunnerB[Task Runner B]
    Provider[Model Providers and Tools]

    User --> TuiA
    User --> TuiB
    TuiA --> Service
    TuiB --> Service
    Service --> Database
    Database --> RunnerA
    Database --> RunnerB
    RunnerA --> Provider
    RunnerB --> Provider
    RunnerA -->|TaskSend / Events| Database
    RunnerB -->|TaskSend / Reports| Database

RuntimeTaskService 是 CLI、TUI 和模型工具共享的行为层。SQLite 保存权威状态，事件游标负责跨进程唤醒和恢复；TUI 只负责投影视图和提交用户操作，不持有第二份 Agent 或 Session 写入状态。

• Python 3.11 或更高版本
• uv
• 至少一个可用的模型 Provider 和 API Key

uv sync --dev

Windows PowerShell：

Copy-Item .codeplus\config.yaml.example .codeplus\config.yaml

Linux 或 macOS：

cp .codeplus/config.yaml.example .codeplus/config.yaml

编辑 .codeplus/config.yaml，填写自己的 Provider、模型和 API Key。该文件默认作为本地配置使用。

启动交互式 TUI：

uv run codeplus

主要目录：

codeplus/
  runtime_tasks/   用户可见任务、协调器、worker 和独立 TUI
  teams/           内部 Team 与共享工作项协调
  agents/          子 Agent 加载、执行和跟踪
  tools/           本地、任务、Skill 和协作工具
  permissions/     权限模式、规则、沙箱和危险命令检测
  mcp/             MCP 客户端、管理器和工具包装
  memory/          Session、自动记忆和上下文召回
  worktree/        Git worktree 生命周期
tests/             单元、持久化、TUI 和运行时集成测试

运行完整测试：

uv run pytest

CodePlus 是一个独立项目，不是 OpenAI 或 Codex 的官方组件。

它希望回答一个仍在快速变化的问题：当 Agent 不再只是一次性回答，而是能够拥有独立任务、持久上下文、直接通信和长期协作能力时，软件开发工具应该怎样更合理、更高效地组织这些 Agent，同时仍让用户看得见、管得住，并能在关键节点作出决定？

这个问题值得持续探索，也值得做成一个能够长期使用的完整工具。