CocurdexAgent
内置 Agent、ACP Registry Agent、权限、协作模式，以及 Cocurdex 如何让多会话工作清晰可读。
Cocurdex 在一个工作区里协调多个 Agent 会话。预发布期间运行时和 provider 仍在演进；本页描述产品模型和当前可用的 Agent。
心智模型
- 每个会话都有明确的状态和推导出的注意力状态（见桌面工作台）。
- 你可以运行多个会话，而不必合并成一条对话记录。
- 权限、提问和计划批准会浮现在 UI 中，而不是静默发生。
- 优先选择仍能完成任务的最窄权限和写入模式。
支持的 Agent
Cocurdex 内置四个 Agent，并可以添加 ACP Registry 上发布的任意编码 Agent。
Id(--agent) | UI 名称 | 运行时 | 说明 |
|---|---|---|---|
claude-agent | Claude Agent | 外部 claude CLI(2.0.0 及以上) | 计划模式、引导、本地写入 |
codex | Codex | 外部 codex CLI | 计划模式、引导、本地写入；授权经由 Codex 自身 |
opencode | OpenCode | 外部 opencode CLI(2.0.20 及以上) | 通过 OpenCode 原生 plan agent 提供计划模式、流式输出；不支持引导 |
pi | Pi | 内置 | 使用你的 Provider 配置和 MCP 服务器；只读写入模式 |
acp:<registry-id> | Registry 中的名称 | 你安装的任意 ACP Registry Agent | 本地写入；计划模式与引导取决于具体 Agent |
常用的 Registry Agent：
Id(--agent) | UI 名称 | 启动命令 | 说明 |
|---|---|---|---|
acp:cursor | Cursor | cursor-agent acp | 流式输出、本地写入；通过 Cursor 登录 |
acp:devin | Devin | devin acp | 流式输出、本地写入；通过 Devin 登录 |
acp:grok-build | Grok Build | grok agent stdio | 计划模式、引导、本地写入；显示套餐用量 |
外部 Agent 必须在你的机器上安装并完成授权。设置 → Agent CLI 会显示每个 Agent 探测到的版本和状态（可用、未安装、需要升级）、可复制的安装命令和文档链接。低于最低版本的 Agent 仍可使用，但在更新前部分能力可能无法工作。
从旧版本升级
Cursor、Devin 和 Grok Build 过去是内置 Agent，id 为 cursor、devin、grok-build。现在它们通过 ACP Registry 运行，id 变为 acp:cursor、acp:devin、acp:grok-build。已有会话和角色会自动迁移；如果脚本里用旧 id 传 --agent，请一并更新。
ACP Registry Agent
ACP Agent 使用 Agent Client Protocol。Cocurdex 从 Agent 自身读取模型目录和会话模式，因此你看到的选项会跟随已安装的版本。
添加方法：打开 设置 → Agent CLI → 从 ACP Registry 添加，搜索官方 Registry，点击安装。执行前 Cocurdex 会先展示安装计划：
| 分发方式 | 安装时做什么 |
|---|---|
| 二进制 | 把对应平台的压缩包下载到应用数据目录；Registry 提供校验和时会校验 |
| npx / uvx | 运行一次包管理器，把固定版本的包缓存到本地；之后启动直接复用缓存 |
| 本地 CLI | 不下载任何内容——直接运行在 PATH 上找到的 CLI |
Registry Agent 属于第三方代码：安装前请先查看它的源码和许可证。移除可以再次卸载。
- 如果
cursor-agent、devin或grok已在PATH上，Cocurdex 首次启动时会自动接管它们。 - 使用自己的命令可以注册 Registry 未收录的 Agent（或自定义构建）：先自行安装，再填写可执行文件名或绝对路径，以及进入 ACP 模式所需的参数。
- ACP Agent 进程意外退出时，下一轮会重新拉起它并恢复同一个 provider 会话。
如何选择运行时
| 场景 | 从这些开始 |
|---|---|
| 你已经在用 Claude Code / Claude CLI | claude-agent |
| 你已经在用 OpenAI Codex | codex |
| 你在别处使用 OpenCode | opencode |
| 你有 Cursor 订阅 | acp:cursor |
| 你在用 Devin | acp:devin |
| 你想要偏 Grok 的实现 | acp:grok-build |
| ACP Registry 上的其他 Agent | acp:<registry-id> |
| 不需要本地工作区写入的轻量对话轮次 | pi(Pi) |
Provider 与模型
Agent 使用应用中注册的 provider 配置（API base URL、凭据、目录）和模型。在桌面 UI 中配置 provider;从 CLI 列出：
cocurdex provider list
cocurdex provider models <provider-id>Cocurdex 会尽可能复用你已有的 provider 配置(例如 ~/.codex 下的 Codex 账户状态)。不要把密钥贴进产品笔记或公开文档站。
权限模式
权限模式因 Agent 而异。风险等级：
| 风险 | 意图 |
|---|---|
| normal | 询问或谨慎门控工具使用 |
| elevated | 更宽松地自动批准编辑 / 评审 |
| dangerous | 完全或绕过式访问——谨慎使用 |
Claude Agent
| 模式 id | 风险 |
|---|---|
claude-default | normal |
claude-accept-edits | elevated |
claude-auto | elevated——当安装的 Claude CLI 支持 auto 模式时提供；Haiku 模型不可用 |
claude-bypass-permissions | dangerous |
当协作模式为 plan 时，会话使用 claude-plan（只做计划，不编辑也不执行命令）。切回 default 会恢复为 claude-default。
Codex
| 模式 id | 风险 |
|---|---|
codex-read-only | normal |
codex-auto | elevated |
codex-full-access | dangerous |
Grok Build(acp:grok-build)
| 模式 id | 风险 |
|---|---|
grok-ask | normal |
grok-auto | elevated（Grok 自己的风险分类器；可能产生额外的模型调用） |
grok-always-approve | dangerous |
OpenCode
| 模式 id | 风险 |
|---|---|
opencode-ask | normal |
opencode-allow | elevated |
opencode-deny | normal |
其他 ACP Registry Agent
Cursor、Devin 及其他 Registry Agent 在 Cocurdex 侧没有独立的权限模式列表。工具审批遵循 Agent 自身的 ACP 权限请求，和其他 Agent 一样以权限卡片呈现。许多 Registry Agent 仍会在输入框里提供会话模式（例如 Devin 的询问 / 计划 / 自主）。这些选项来自已安装的 Agent，而不是 Cocurdex 的一张表。
内置 Pi(pi)
没有独立的权限模式列表；写入模式为 read-only。
当 Agent 请求特权操作时，Cocurdex 会浮现一张权限卡片（可能附带路径/操作细节）。在会话 UI 或 CLI 的 session tui 中处理。
协作与写入模式
| 控制项 | 取值 | 含义 |
|---|---|---|
| 协作模式 | default、plan | 运行时支持计划优先循环时的计划模式 |
| 写入模式 | read-only、native-write | 工具是否可以修改工作区 |
不是每个 Agent 都支持每种组合。ACP Registry Agent(包括 Grok Build)只支持本地写入；内置 pi 只读。
Agent 角色
Agent 角色是保存好的预设：Agent + provider/模型 + 权限模式 + 协作与推理轴，外加可选的指令和 skills。每个角色还有一个头像（彩色底上的 emoji 或首字母，并带有 Agent 图标角标）和可选的描述，说明它擅长什么——团队 lead 挑选队友时会参考描述。
在输入框中保存角色：在新会话里打开模型菜单，选择保存为角色。在 设置 → 角色 中编辑或删除，并从 CLI 列出：
cocurdex role list新建会话时可以直接套用角色，也可以把角色分配给队友或脚本编排的子 Agent。
Cocurdex Agent 工具
daemon 为每个会话挂载一个本地 MCP 工具服务。工具按组划分，只在合适的场景提供：
| 分组 | 工具 | 提供给 |
|---|---|---|
team | spawn_teammate、spawn_template、list_roles、list_templates、stop_member、stop | 主会话（团队 lead） |
team | task_create、task_list、task_update | 主会话与队友 |
messaging | list_agents、send_message | 主会话与队友 |
script_run | propose | 主会话 |
settings | list、get、set、propose | 主会话（也驱动设置助手） |
脚本编排启动的子 Agent 不获得以上任何工具。能够委派工作的会话还会收到指引：同一 provider、只要结果的工作用 Agent 自带的原生子 Agent；需要其他 provider、已保存角色、独立工作树或任务依赖时，用 Cocurdex 团队或脚本编排。具体用法见团队与编排。
会话内控制
一些运行时可以在不重建 provider 会话的情况下切换模型、思考/推理力度、权限或相关轴。这能保持对话连续性和 provider 侧的缓存。如果某个 Agent 缺少某个控制项，那是有意不支持——没有「暗中重启会话」的兜底。
会话空闲时，也可以在输入框里切换 Agent，或分叉会话（以及在用户消息上从这里分叉）。见分叉与切换 Agent。执行树展示嵌套的运行和工具调用。
设置 → Agent CLI → 运行上限 限制并发的委派工作；你自己发起的会话不会被排队。见 Provider 与设置。
引导与后续输入
当 Agent 支持引导(steering)时，你可以在运行进行中发送后续指引（或把后续输入排队到当前轮次结束——可在对话设置中配置）。当引导不可用时，等待当前轮次结束或停止会话。
从 UI 或以下命令停止运行中的会话：
cocurdex session stop <session-id>并行会话
典型模式：
- 一个会话实现功能
- 一个会话排查 bug 或评审分支
- 可选的计划模式会话做设计
标题保持简短，状态保持可见。只在有注意力需求时切换——不要为了「省一个会话位」把不相关的工作塞进同一条对话记录。