Agent 集成¶
本页说明如何接入和使用已有 Agent。如果要构建新的 Raven Agent,请读构建 Agent; 如果要实现 ACP、CLI、HTTP 或其他后端,请读协议与后端集成。协议消息和 生命周期请读Agent 协议。
Agent 来源与运行方式¶
“Raven Agent”和“外部 Agent”描述 Agent 的提供方;kind 描述 Raven 使用的运行后端。
两者是独立维度:随 Raven 发布的 Agent 也可能通过 ACP 运行,外部 Agent 也可能通过 ACP、CLI
或 HTTP 接入。
| 集成类型 | 运行配置 | 执行边界 |
|---|---|---|
| 进程内后端 | kind: builtin |
宿主进程中的 Raven loop |
| 随 Raven 发布的 Agent | 发现到的目录、kind: acp |
启动器用 Agent 自身配置启动 Raven |
| 本地外部 Agent | subagents.agents 中的 kind: acp 或 kind: cli |
另一产品的进程和原生策略 |
| OpenAI-compatible HTTP Agent | subagents.agents 中的 kind: openai |
远程端点;此后端没有本地工具循环 |
| A2A peer | a2a.peers 与 a2a_send |
独立宿主,不属于子 Agent roster |
spawn 与 DAG 节点使用同一 roster。节点必须使用当前工具实际公布的名称或 worker
label;熟悉的产品名本身不会安装、启用或认证 Agent。
Raven 原生 Agent¶
| Agent | 适合任务 | 关键边界 |
|---|---|---|
| Raven-Code | 编码、调试与验证 | 会真实修改文件;并行写入应划分文件,todo 完成只是模型声明,不是测试证据。 |
| Raven-Design | 视觉设计、评审和演示文稿 | 需要 design/media 就绪;deck 请求会路由到隐藏的 Raven-PPT。 |
| Raven-Oncall | 执行并观察多轮或远程任务 | 需要目标机器、预算和停止条件;首次响应不代表任务完成。 |
| Raven-PPT | 制作 .pptx deck |
通常通过 Raven-Design 进入;需要 deck engine、模板、渲染和媒体条件。 |
| Raven-Research | 实时网页研究和有来源报告 | 需要 research profile 与凭据;不是通用编码或聊天委派 Agent。 |
五个定义不一定对应五个可见名册条目。随 Raven 发布的 Raven-PPT manifest 隐藏在 Raven-Design 的路由后;操作者本地 manifest 可能不同。路由还考虑声明的需求、附件和 tier,因此任务 不总是在与可见条目同名的实现上运行。
Agent 从目录发现,包括用户拥有的 $RAVEN_HOME/agents/。就绪状态取决于实际启动
解释器中的 runtime 和声明的 engine wheel。修改定义后重启常驻宿主,确保重建 live
roster。不要假定修改显示名就创建了新身份。可通过 raven onboard 或 WebUI 的 Agent 设置
完成配置。
从 TUI、WebUI 或已配置的消息渠道发起任务时,在请求中写明目标 roster 条目,并说明工作目录、
允许的副作用和预期证据。DAG 节点应使用当前工具公布的 roster 名称;生成的 worker label
只在当前 run_subagent_dag 调用中有效。存储的 Playbook 必须使用已注册的 roster 名称,
不能使用当前轮次的 label。当前 roster 中不存在的显示名不会选择 Agent。
调用五个原生 Agent¶
| 调用入口 | 支持情况 | 说明 |
|---|---|---|
宿主通过 spawn 委派 |
五个 Agent 均支持,前提是已启用且 ready | 从 TUI、WebUI 或已配置渠道请求;使用实际公布的 roster 名称。Raven-PPT 通常通过 Raven-Design 路由进入。 |
| 有状态 instance 会话 | 支持并公布 stateful session 的 ACP Agent | 通过 WebUI instance 面板或对应 RPC 继续会话;依赖 live capability snapshot,不要仅凭配置推断 resume 支持。 |
run_subagent_dag 节点 |
当前 roster 公布的 Agent | 在 subagent 中填写 roster 名称;生成的 Worker Table label 只在当前轮次有效,不能用于存储的 Playbook。 |
| Playbook | 已注册的 roster Agent | Playbook 最终使用同一个 DAG registry;常规 Raven-PPT 流程应使用 Raven-Design。 |
| 直接通过 stdio 调用 ACP | 五个 Agent 均支持 | 启动产品 launcher,发送按行分隔的 JSON-RPC。Raven-Research 默认提供 ACP,不使用 --acp 参数。 |
| 单次 CLI hosting | 仅 Raven-Code | 使用 launcher 的 --task 或 --prompt-file;--session 可继续 CLI 会话。 |
| 消息渠道 | 五个 Agent 均可被宿主间接委派 | 消息先进入 Raven 宿主,再使用相同 roster 和权限进行委派。 |
| 直接通过 A2A 调用单个原生 Agent | 不支持 | A2A 暴露的是 Raven 宿主,不是五个独立的原生 Agent endpoint。 |
前四种是宿主层的委派方式;只有直接 ACP 和 Raven-Code CLI hosting 会显式启动原生产品 launcher。readiness probe 成功或收到委派回执,都不代表任务已完成;仍需检查结果、文件、 测试或报告产物。
与宿主共享内存¶
每个原生 Agent 都是一个独立的 Raven 进程。宿主 config.json 中 subagents.runtime
下的三个设置让它不必每个 Agent 都占用一整份 Raven 的内存。三者默认开启,并实时读取,
修改后从下一次启动起生效。
| 键 | 默认值 | 作用 |
|---|---|---|
idleCloseS |
600 |
Agent 空闲达到该秒数(双方都没有在途请求,也没有任何消息)后关闭其进程。仍持有已设定的提醒或正在运行的插件服务的 Agent 会被保留。只关闭能重新打开会话的 Agent(声明了 loadSession 或 sessionCapabilities.resume),因此下一轮会在新进程中续上原会话。0 或 null 表示一直保留到宿主退出。 |
llmRelay |
true |
由宿主代为发出原生 Agent 的 LiteLLM 调用,Agent 自身不再加载 LiteLLM。请求组装、重试和用量记录仍由 Agent 自己完成。若 Agent 自己的 env 设置了 LLM 端点、云凭据、代理或 CA 证书,它会自己发起调用。 |
forkTemplate |
true |
在 Linux 上,原生 Agent 从一个已加载 Raven 的进程 fork 出来,共享这些内存页,而不是各自加载一份。其他系统仍按原方式启动。 |
模板只预加载至少两个原生 Agent 共用的模块,某个 Agent 独有的模块由它在 fork 之后自行
导入,因此模板的大小取决于各 Agent 的共同部分,而不是 Agent 的种类数。模板本身也是一个
进程,因此同时运行两个及以上原生 Agent 时才会省内存;只有一个 Agent 时,它的占用会略多于
它省下的部分。只会运行单个 Agent 的设备可将 forkTemplate 设为 false。中转或模板无法服务的 Agent(宿主不可达,或 Agent 使用另一个解释器)
会按原方式启动。
最小 ACP 调用¶
随 Raven 发布的每个 Agent 都由自己的 launcher 启动。使用对应命令:
| Agent | Launcher 命令 | 说明 |
|---|---|---|
| Raven-Code | python agents/raven-code/run.py --acp |
也支持单次 CLI hosting。 |
| Raven-Design | python agents/raven-design/run.py --acp |
需要 design engine。 |
| Raven-Oncall | python agents/raven-oncall/run.py --acp |
运维任务需要已注册的目标机器访问。 |
| Raven-PPT | python agents/raven-ppt/run.py --acp |
通常通过 Raven-Design 路由;需要 PPT engine。 |
| Raven-Research | python agents/raven-research/run.py |
默认就是 ACP hosting;该 launcher 没有 --acp 参数。 |
使用已安装 Raven 和 Agent 所需 engine wheel 的解释器。常规制作 deck 时,应通过 Raven-Design 请求,而不是直接选择隐藏的 Raven-PPT 路由。
以下以 Raven-Code 为例:
python /absolute/path/to/Raven/agents/raven-code/run.py --acp
Launcher 会渲染该 Agent 的配置,并通过 stdin/stdout 启动 raven acp。每行发送一个
JSON-RPC 对象;日志和 wrapper 输出不能写入 stdout。进程启动后,最小可用的请求序列是:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/absolute/path/to/project","mcpServers":[]}}
{"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"<session-id-from-session-new>","prompt":[{"type":"text","text":"Reply with one sentence; do not edit files."}]}}
| 字段或参数 | 含义 |
|---|---|
--acp |
通过 stdio 提供 ACP 服务,不是 HTTP 监听器。 |
python |
使用已安装 Raven 和 Agent 所需 engine wheel 的解释器。 |
protocolVersion |
握手时请求的 ACP 版本;当前 Raven 使用 1。 |
clientCapabilities |
调用方能够处理的能力;最小声明可以是 {}。 |
cwd |
当前 session 的绝对任务工作目录,不是 Agent 的 ACP home。 |
mcpServers |
当前 session 的 stdio MCP 附件;不需要时传 []。 |
sessionId |
session/new 返回的标识,后续 prompt 继续复用。 |
prompt |
内容 block 数组;最小 block 包含 type: "text" 和 text。 |
服务端可能在这些请求之间发送 session/update 通知。客户端应持续读取,并在等待最终
prompt 响应前处理权限或问题请求。完整生命周期和协商能力见Agent 协议。
任务提示模板¶
使用实际公布的 roster 名称,并写明任务范围、允许的副作用和预期证据。以下一句话模板 只是起点,不代表任务已经可以运行或已经完成:
| Agent | 示例请求 |
|---|---|
| Raven-Code | Raven-Code:检查 src/parser.py 中的 parser;只编辑 parser 文件;运行对应测试;报告命令输出。不提交、不推送。 |
| Raven-Design | Raven-Design:评审这个 dashboard 的层级和可访问性;提出具体视觉修改,并将反馈保存到项目工作区。 |
| Raven-Oncall | Raven-Oncall:在已注册的 lab machine 上运行参数 sweep;预算两小时;停止失败 worker;比较每轮结果并报告最终产物。 |
| Raven-PPT | Raven-PPT:根据这些笔记制作产品评审 .pptx;常规流程优先使用 Raven-Design;逐页渲染并返回未解决问题。 |
| Raven-Research | Raven-Research:使用过去一年发布的来源比较这些方案;为重要结论附 URL,并将报告写入指定工作区文件。 |
对每个 Agent,都应在真实任务前检查 readiness,并在任务后检查最终回答、生成文件和执行证据。 ACP readiness 或 roster 中列出条目,只能证明进程可以启动,不能证明任务已成功完成。
Raven-Code:工作区与验证边界¶
Raven-Code 的 code-flow 提供的不只是身份 prompt。每个任务都应绑定项目目录,明确文件所有权、
允许的副作用和验证命令;完成后检查实际文件、命令输出和 Harness Manifest。
| 范围 | 边界 |
|---|---|
| 项目指令 | AGENTS.md、CLAUDE.md 和 CONTEXT.md 从工作目录读取,受配置选择、路径范围和 prompt 预算约束;它们不是 Agent home 的 bootstrap 文件。 |
| 文件与工作区状态 | 文件工具跟踪 session 读取过的版本;启用 read-before-edit 时,未读或被外部改变的版本会被拒绝。共享 checkout 会看到相同 HEAD 和修改;并发提醒与 read ledger 不是文件锁或 worktree 隔离,完整写入也不普遍受保护。 |
| 任务状态 | todo 按 session 持久化;完成状态是模型声明,不是测试证据。已有 session 会恢复清单,新任务应使用真正的新 session;宿主原地 /new 保留 session key,可能不会重置这份产品清单。 |
| Git 证据 | Harness Manifest 通过 ACP response metadata 报告修改、提交、阻碍和共享工作目录归属;不要根据模型说“就绪”推断 Git 事实。 |
| 产品配置 | Raven-Code launcher 会启用产品配置。仅在别处安装 code-flow 不会启用所有能力;提醒/报告与替换工具面有独立开关。 |
请求示例:“阅读项目指令,只在分配给你的文件内修复 parser bug,运行对应测试, 报告剩余修改或阻碍。不提交、不推送。”
追问协作见与子 Agent 协作,后台长任务见长任务托管(Oncall)。 启动器和 harness 细节见实现案例。
接入外部 Agent¶
以下是当前源码声明的预设,表示支持的配置路径,不代表每个供应商版本或你的本地 安装都已通过真实任务验证。
| 预设 key | 传输与启动方式 | 使用前检查 |
|---|---|---|
claude_code |
通过 npx 启动 ACP 适配器 |
适配器下载/runtime 和子 Agent 认证 |
codex |
通过 npx 启动 ACP 适配器 |
预设设定 INITIAL_AGENT_MODE=agent-full-access,需评估宿主和网络访问 |
opencode |
opencode acp |
当前预设以 sessionMcp: false 阻止每会话 MCP 下发 |
hermes |
hermes acp --accept-hooks |
原生认证;该标志接受之前未见的 Shell hook |
openclaw |
openclaw acp |
自身网关、认证;启动使用较长握手等待 |
minimax_code |
mcode acp |
原生 ACP server;需要 Node.js 22.19-22.x 或 24-26.x。用 npm install -g @minimax-ai/code --allow-scripts=@minimax-ai/code,better-sqlite3 安装 CLI(npm 12 不批准安装脚本时会装出不完整的包;npm 11 及更早的版本照常执行安装脚本,其中不认识这个参数的版本会打印一条警告,但安装照样完成),再用 mcode login 登录——账号不在 cn 区(CLI 默认的账号站)时,加上 --region global(或 --region cn)。如果桌面端已经登录,把 MINIMAX_DATA_DIR 指向它数据目录的绝对路径(即 ~/.minimax 展开后的目录,例如 /Users/<you>/.minimax 或 C:\Users\<you>\.minimax),可以写在这个 agent 在 ~/.raven/config.json 里的 env,也可以写进 Raven 启动 agent 时读的环境变量(POSIX 上按“重新检测”会重新读一遍登录 shell 的环境;Windows 上子进程继承的是 Raven 自己的环境,需要重启 Raven)。 |
dsh |
dsh --profile acp |
已安装 DSH(npm install -g @deepseek-ai/dsh,需 Node.js 24.9 及以上)并完成登录;它声明 session/resume、不声明 loadSession,Raven 用 session/resume 续接它的会话 |
mirothinker |
OpenAI-compatible HTTP | 端点、模型、key;预设关闭有状态重放 |
mirasim_<agent> |
Raven 自带的 ACP 适配器,经 Mirasim host 的协议调用 | 本机装了 Mirasim 且正在运行,该 Agent 已在 Mirasim 中安装。Raven 找到 Mirasim 就会列出这些行:有能连上的 host(Mirasim host 写出了令牌的端口,例如桌面应用或 mirasim serve 的端口,或 Mirasim 经 ssh 在本机跑的服务器的套接字,二者都要真的应答),否则看 Mirasim 写在自己目录下的启动器(~/.mirasim/bin/mirasim,它不会把这个目录放进 PATH)、登录 shell PATH 上的 mirasim,或某个 Mirasim 经 ssh 装到本机的服务器(~/.mirasim-remote);装了但没在运行时,这一行会提示打开 Mirasim 应用或启动 mirasim serve,或让另一台电脑上的 Mirasim 应用重新连到本机。以 sessionMcp: false 阻止每会话 MCP 下发 |
GitHub Copilot、Qwen Code、CodeBuddy、Qoder、Grok Build、Kimi Code 和 Pi 也有预设。
适配器版本与精确命令维护在 raven/agent/subagent/presets.py、
raven/agent/subagent/acp_registry_presets.py 和
raven/agent/subagent/mirasim_presets.py,优先使用已安装版本的预设,不要自行猜 flags。
mirasim_* 预设接入 Mirasim 运行的 Agent,每个 Agent 一行:
Claude Code、Codex、Kimi Code、Antigravity、Qwen Code、Grok Build、DSH、Pi 和 ZCode CLI,
名称形如 Claude Code-Mirasim。这样一行代表在 Mirasim 所设账号与模型路由上运行的该
Agent,因此可以与同一 Agent 自己的预设并存。适配器随 Raven 发布(raven/acp/mirasim/),
无需下载;命令中的 {PYTHON} 在写入配置时替换为 Raven 自己的解释器;若该解释器之后不复存在
(例如安装位置发生变化),下次读取配置时该行会改指当前运行 Raven 的解释器。可选模型取自
Mirasim 为该 Agent 提供的列表,分为三组:Agent 自己名下的模型、Mirasim(平台额度)
和 Own key(你在 Mirasim 中添加的 key)。Mirasim 平台也能运行 Claude Code、Codex、
Kimi Code 和 ZCode CLI 的自有模型,因此这四个 Agent 的这些模型在前两组各列一次:
选 Agent 名下的走你自己的账号,选 Mirasim 下的走平台额度。每一轮都会带上所选模型对应的
路由,因此已有会话改选另一组后,从下一轮起即切到那条路由。未选模型的会话使用 Mirasim
为该 Agent 设定的默认模型和默认路由。
适配器是本机已在运行的 Mirasim host 的又一个客户端——桌面端的 host、mirasim serve
运行的 host,或 Mirasim 经 SSH 接入的机器上的 host——自身不启动任何服务,Raven 发起的轮次在 Mirasim 应用中实时可见。
每轮以流式返回:思考、正文、工具调用、计划和交付的文件随发生随送达 Raven,结束时报告
所用上下文。取消会停止该轮。对 Claude Code、Codex、DSH、Pi 和 ZCode CLI,运行中追加的
文字会并入当前轮。图片以内联方式送达 Claude Code;其他 Agent 收到以本地文件链接给出的
图片时得到该文件的路径,内联图片则会被拒绝。会话可以列出(指定目录下该 Agent 的会话,
包括在 Mirasim 中开启的)、续接、连同全部历史载入、关闭和删除;删除时 Mirasim 中的会话
一并删除,Agent 自己保存的转录文件不会删除。Raven 持有的会话里由 Mirasim 自行发起的轮次
(例如后台任务的报告)也会转给 Raven,这类轮次中的提问留给 Mirasim 应用处理。
适配器按以下顺序查找 host:Mirasim 经 SSH 接入的机器上的 host socket
(~/.mirasim-remote/run/server.sock,仅限 Linux 和 macOS),然后是 Mirasim 状态目录
(MIRASIM_HOME,否则为 ~/.mirasim)下每个以 run/local-<port>.token 写出了 token
的本机回环端口:先试桌面端的 4970,再试 mirasim serve 默认监听的 4939,其余按端口号
从小到大,第一个应答的就是 host;写出了 token 文件的端口只有在它的 /api/health
自称 Mirasim host 时才算应答,该文件里的 token 只会发给自证了身份的 host,不会发给之后
占用该端口的其他程序。health 答不出来的 host 仍可用 RAVEN_MIRASIM_HOST 指名接入。
host 按实际绑定的端口写这个文件,所以因原端口被占而换了
端口的 host 照样能找到,被强行结束的 host 留下的文件会被跳过,host 重启后换了端口,适配器
重连时也会到新端口找它。若 host 监听在其他位置,用
RAVEN_MIRASIM_HOST 指明:socket 写作 unix:<path>(Windows 不支持,那里经桌面端的
端口接入),本机回环端口写作 <port>、127.0.0.1:<port>、localhost:<port> 或
[::1]:<port>。在 Linux 和 macOS 上,适配器使用的是登录 shell 的环境加上该行自己的
env,而不是 Raven 进程的环境,所以请把这个变量写进 shell 配置文件,或写进要使用它的
Mirasim 行的 env;只在启动 Raven 的 shell 里 export 是传不到适配器的。在 Windows 上,
适配器继承 Raven 自己的环境,在启动 Raven 的地方设置即可。
Raven 发起的轮次停下来等待的事项会在等待期间转交 Raven:工具审批以权限请求发出;提问——Mirasim
开启 askTool 设置时 Claude Code 的 AskUserQuestion,或 MCP 服务器的表单——以
elicitation 发出,由你或 Raven 的提问自动作答回答。不支持表单的客户端会跳过该提问,
并在回复中写明所问内容。
提问、选项、回复和错误详情保留发送方 Agent 的内容。脱敏由该 Agent 自行决定;
即使回传值与 Raven 自身持有的凭据相同,Raven 也不替换。
判断兼容性时区分三个结论:
- 已声明预设: Raven 有配置模板。
- 握手/探测成功: 当前安装能启动并报告能力。
- 任务已验证: 真实任务验证了认证、工具和输出。
手写集成需要对所有适用层级分别检查。
接入与验证¶
- 按外部 Agent 对应版本安装并认证,确保其可执行文件在常驻 Raven 进程的
PATH中。 - 通过 WebUI Agent 设置配置,或向宿主配置的
subagents.agents添加配置条目;保留其他条目和设置。 - 检查配置和 readiness 结果。ACP probe 可能启动进程,shim 可能下载代码;完整任务测试可能消耗模型额度。
- 先运行“只用一句话回答,不编辑文件”等低风险任务,再分别验证文件、工具或 resume 能力。
- 检查权限与隔离后,才扩大委派范围。
使用已安装 Hermes 可执行文件的最小 ACP 示例:
{
"subagents": {
"agents": [
{
"name": "Hermes Agent",
"preset": "hermes",
"kind": "acp",
"enabled": true,
"command": "hermes acp --accept-hooks",
"cwd": "/absolute/path/to/project",
"readyTimeoutMs": 30000,
"timeout": 600
}
]
}
}
这是合并片段,不是完整配置替换;hook 标志具有上文说明的安全影响。ACP command
启动 server,不应包含 {prompt}、{prompt_file} 或 {agent_id}。
readyTimeoutMs 限制握手,timeout 限制任务;后者省略时默认没有自动期限。
CLI 后端的 command 是 argv 模板。{prompt} 作为一个参数替换,{prompt_file}
指向 prompt 文件,无占位符时走 stdin。resumeCommand 必须包含 {agent_id};
id 分配方式和会话记录解析必须符合该 CLI。不要把这些字段复制到 ACP 配置条目。
HTTP 后端配置 baseUrl、model 和凭据,而不是命令。宿主重放可提供历史,但不等于
远程原生会话。此后端不能读取本地路径或接收 MCP 下发。OpenAI-compatible Agent
端点与修改 Raven 主模型 provider 是两件事。
文件、状态与凭据¶
| 位置或 handle | 职责 |
|---|---|
| 用户工作目录 | 任务获准读取或修改的文件 |
| 宿主 Agent home | 宿主身份、会话、技能和记忆 |
| Agent state root | Launcher 渲染配置与 Agent 工作状态 |
| Agent ACP home | 子引擎身份、transcript 和 skill pool |
instance |
在后端支持时续接子 Agent 会话 |
| Node id | 寻址宿主会话中记录的任务和输出 |
CLI 的 readsLocalFiles 是对其执行环境的声明。ACP 能力通过协商并由适配器解释。
HTTP 后端没有本地文件访问,应传有界内容而不是宿主路径。只有 Agent 真正支持相应
记忆路径时才配置 memory identity;添加元数据不会让外部产品自动共享 Raven 记忆。
凭据不要放进 prompt 和共享 manifest。A2A 凭据按 origin 而不是显示名匹配;peer 列表不是出站防火墙,详见A2A 指南。
原生 Agent 放在 ACP home 里的提示词文件(agent_memory/profile/ 下的 soul.md、
agent.md,以及 TOOLS.md)每次启动都会按当前版本和配置重新生成,直接修改不会保留。
自己的内容请写进同目录的 *.local.md(例如 agent_memory/profile/agent.local.md),
下次启动时会接在产品文本之后。只放仍然需要的内容:旧版本的文本可能与当前规则冲突。
*.local.md 请保存为 UTF-8;其他编码(例如编辑器按 GBK 保存)会导致启动停止,报错会写明是哪个文件。
被直接修改过的文件、或旧版本留下的文件,会在覆盖前保存为 <name>.bak-<时间>-<pid>,launcher
日志会写明备份位置。重新生成的文件保留原文件的访问权限。在 Windows 上,备份是指向原文件的硬链接,
因此同样保留这些权限;如果所在的卷不支持硬链接,启动会停止并给出文件名。备份不会被自动删除。
Raven-PPT 有一点不同:它的 deck engine 可能和 host 共用同一个 home,所以只替换能证明是自己写的文件。
本版本之前被修改过的 soul.md、agent.md 或 TOOLS.md 会保持原样,不做备份,对应的 *.local.md
也不会生效。请把仍需要的内容移到 *.local.md,再删除修改过的文件,下一轮会重新写入。engine 写入失败时
会记录日志并在下一轮重试,不会让本轮停止。
安全与排障¶
出站 ACP 自动优先选择对方提供的 allow 选项。父级 permission mode 不为每个外部 Agent 内部操作提供人工审批。无人值守委派前,应检查原生权限、账户权限、可写挂载、 hook 和网络访问。
| 现象 | 检查 |
|---|---|
| Agent 不在可选 roster | Discovery、enabled/hidden、路由、readiness |
| Engine 不可用 | Wheel 是否在子进程解释器里,而不只是另一虚拟环境 |
| 握手通过但任务失败 | 模型凭据、工具前置条件、子进程 stderr |
| CLI 输出缺失或乱码 | 退出状态、transcript 格式、输出解析 |
| Instance 无法续接 | Resume 契约与协商出的会话能力 |
| MCP 选择未下发 | 后端支持和 sessionMcp 隔离策略 |
| 远程 Agent 无法打开文件 | 是否把宿主路径误当作内容传输 |