常见问题 (FAQ)¶

工具调用相关¶

Q: 工具调用返回 "当前工具需要调用前进行二次确认" 错误¶

问题描述:

{
  "content": [
    {
      "type": "text",
      "text": "当前工具需要调用前进行二次确认，但客户端目前没有实现二次确认回调方法"
    }
  ],
  "isError": true
}

原因: 被调用的工具在配置中启用了二次确认，但客户端未实现确认回调。

解决方案:

方案 A: 为特定工具关闭二次确认

{
  "tool_meta": {
    "工具名": {
      "auto_apply": true
    }
  }
}

方案 B: 为所有工具关闭二次确认（使用默认配置）

{
  "default_tool_meta": {
    "auto_apply": true
  }
}

Q: 工具调用超时¶

可能原因: - 工具执行时间过长 - Computer 不在线 - 网络连接问题

解决方案: 1. 增加 timeout 参数值 2. 检查 Computer 是否正常运行 3. 检查网络连接

Q: 找不到工具¶

可能原因: - MCP Server 未启动 - 工具名称错误 - 工具在 forbidden_tools 中

解决方案: 1. 使用 tools 命令查看可用工具列表 2. 检查 MCP Server 状态：status 3. 检查配置中的 forbidden_tools

Desktop 相关¶

Q: 一个 MCP Server 能暴露多少个 window:// 资源？¶

答: 没有限制。一个 MCP Server 可以暴露多个 window:// 资源，通过 window://{host}/{path} 区分不同窗口。Computer 会从 resources/list 返回中筛选所有 window:// 资源。

Q: Desktop 是如何组装的？¶

组装流程: 1. 跨 MCP Server 汇总所有 window:// 资源 2. 读取每个 window 的内容 3. 按策略排序/裁剪 4. 渲染为字符串列表

排序规则: - size 截断: desktop_size 参数控制数量上限 - server 优先级: 最近调用过工具的 Server 优先 - 窗口排序: 同一 server 内按 annotations.priority（float [0.0, 1.0]）降序 - fullscreen 规则: fullscreen 窗口独占该 Server 的显示

Q: 为什么 Desktop 返回为空？¶

可能原因: - 没有 MCP Server 暴露 window:// 资源 - desktop_size 设置为 0 或负数 - MCP Server 未启动 - MCP Server 未声明 resources.subscribe 能力

Q: Window URI 的格式是什么？¶

格式: window://host/path1/path2（纯标识符，不含 query 参数）

host（必需）: MCP Server 资源命名空间根，SHOULD 跨 MCP Server 唯一（非 MUST；冲突时 Computer 记 WARN，运行时按"先注册优先"路由）；推荐反向域名风格如 com.example.mcp 天然回避冲突
path（可选）: 0..N 个路径段，URL 编码

布局元数据自 v0.2 起改为通过 MCP Resource 的 annotations（MCP 标准字段）与 _meta（A2C 扩展字段）声明，不再写入 URI query：

annotations.priority（可选）: 浮点数 [0.0, 1.0]，MCP 标准字段，同一 MCP Server 内比较，越大越靠前
annotations.audience（推荐）: Window 面向 Agent，SHOULD 声明 ["assistant"]；声明 ["user"] 在 v0.2 仅触发 WARN 不过滤
_meta.fullscreen（可选）: 布尔值，A2C 扩展字段，全屏渲染标记

详见 Desktop 桌面系统 - Window URI 规范与 Window 资源元数据。

Q: 如何让 MCP Server 的内容出现在 Desktop 上？¶

MCP Server 参与 Desktop 需满足以下条件：

声明 resources.subscribe 能力
在 resources/list 中返回有效的 window:// URI 的 Resource
实现 resources/read，返回 TextResourceContents
在窗口增删/内容变化时发出对应的 MCP 通知

详见 Desktop 桌面系统 - MCP Server 实现指南。

详见 Desktop 桌面系统完整规范。

DPE 文档相关¶

Q: DPE 和 Desktop 有什么区别？¶

Desktop 管理瞬态上下文（window://），适合小型、频繁变化的数据（如当前浏览器页面、编辑器状态），内容随 Socket.IO 直接传输。DPE 是文档抽象（dpe://），适合大型结构化内容（如 Excel 表格、PDF 文档、PPT 演示文稿）；DPE 内容不走 Socket.IO，由 Computer 端业务 Resolver 转成访问 URI（对象存储 / 本地文件 / 任意 scheme），Agent 用应用层协议（HTTP / file / ...）自取。

Q: 什么是 DPE 三层模型？¶

DPE 代表 Document-Page-Element 三层结构：

Document: 一个完整文档实例（如一个 Excel 工作簿）
Page: 文档内的一个逻辑页面（如一个工作表）
Element: 页面内的一个内容单元（如一个表格、一段文本）

DPE 三层是内容结构层级——通过 Resolver 输出的访问 URI 拉到的 JSON 必须符合 DPE 标准格式（Document JSON 含 pages 数组，每个 Page 含 elements 数组）。URI 层只标识 Document（dpe://host/doc-ref）；Page / Element 在 JSON 内部表达，不在 URI 层级。详见 DPE 内容标准格式。

Q: dpe:// URI 的格式是什么？¶

格式: dpe://{host}/{doc-ref}

DPE URI 是纯文档标识符，只到 Document 一层——Page / Element 是文档内部结构（DPE 内容 JSON 的 pages / elements 数组），不在 URI 层级。URI 不携带 query / fragment，所有元数据通过 MCP Resource 的 _meta / annotations 声明。

doc-ref 支持单段或分段路径，业务方按需选择风格：

dpe://com.example.docs/rpt-2026                      # 单段不透明键
dpe://com.example.docs/reports/2026/annual           # 三段层级路径
dpe://com.example.code/src/main/java/Foo.java        # 含扩展名的代码路径

详见 DPE 文档协议 - URI 规范。

Q: 如何让 MCP Server 暴露 DPE 文档？¶

按 MCP 标准实现即可，无需任何 SMCP 特定改动：

在 resources/list 中返回有效的 dpe:// URI 的 Resource（含 _meta / annotations 元数据）
实现 resources/read，返回对应 ResourceContents（内容形态由 MCP Server 与文档应用层约定，A2C 协议不规定）

详见 DPE 文档协议 - MCP Server 实现指引。

Q: Agent 如何获取 DPE 文档内容？¶

Agent 调用 client:get_dpe(uri=dpe://...) → Computer 调本地业务 Resolver 把 DPE 转成访问 URI → Agent 用应用层协议（HTTP / file / ...）自取实际内容。A2C 协议本身不承载 DPE 文档内容（避免大体量内容压垮 Socket.IO）。

详见 DPE 文档协议 - client:get_dpe 事件。

Q: 为什么 client:get_dpe 返回 4011？¶

4011 DPE Resolver Not Configured 表示 Computer 未注册 DPE Resolver hook。Computer 业务方必须显式实现 Resolver（决定把 DPE 内容投递给 Agent 的方式：上传对象存储 / 落本地缓存 / 任意 URI scheme）。协议不降级到"inline 透传 ResourceContents"——这是设计意图。

详见 DPE 文档协议 - DPE Resolver Hook。

Q: A2C 为什么没有内置 Finder（文档目录浏览器）？¶

DPE 是底层抽象（类比 Linux POSIX 文件 API），Finder 是上层应用（类比文件管理器）。v0.2 协议保持纯粹——只定义 DPE 抽象（URI / 元数据 / 转换 hook），不内置文档发现、检索、聚合视图等"管理类"能力。这些未来作为内置 MCP Server（"Finder"）独立提供，与协议核心解耦。

连接相关¶

Q: Socket.IO 连接失败¶

可能原因: - Server URL 错误 - 认证失败 - 网络问题

解决方案: 1. 检查 Server URL 是否正确 2. 验证 API Key 等认证信息 3. 检查网络连接和防火墙

Q: 加入房间失败¶

可能原因: - 房间已有 Agent（Agent 独占规则） - office_id 格式错误 - 未连接到 Server

解决方案: 1. 确认房间内没有其他 Agent 2. 检查 office_id 格式 3. 先执行 socket connect

配置相关¶

Q: 占位符 ${input:xxx} 未被替换¶

可能原因: - 未加载 inputs 定义 - input id 拼写错误

解决方案: 1. 使用 inputs load @file.json 加载定义 2. 使用 inputs list 检查已有定义 3. 确认 id 拼写正确

Q: 工具名称冲突¶

说明: 当多个 MCP Server 有同名工具时会产生冲突。

解决方案: 使用别名区分

{
  "tool_meta": {
    "read_file": {
      "alias": "local_read_file"
    }
  }
}

性能相关¶

Q: 大量连接时性能问题¶

建议: 1. 使用 Redis 作为 Socket.IO 会话存储 2. 配置合理的连接数限制 3. 使用负载均衡

Q: 工具执行慢¶

建议: 1. 检查 MCP Server 本身的性能 2. 考虑使用异步客户端 3. 合理设置超时时间

开发相关¶

Q: 如何调试工具调用？¶

使用 CLI 的 tc 命令：

a2c> tc {"computer":"local","agent":"debug","req_id":"1","tool_name":"echo","params":{"text":"hello"},"timeout":30}

Q: 如何查看事件流？¶

启用详细日志：

import logging
logging.basicConfig(level=logging.DEBUG)

Q: 同步客户端还是异步客户端？¶

异步客户端: FastAPI、Sanic 等异步框架
同步客户端: Flask、Django 等同步框架

其他¶

如有其他问题，请通过 Issue 反馈，建议附带： - 使用场景描述 - 最小复现配置 - 日志片段 - 相关测试用例