症状：你在 Xcode 27.1 里找不到 Agent 添加入口，或 Agent 已显示却读不到当前项目。
最快解法：要在 Xcode 内使用兼容 Agent，按 Apple 的 ACP 入口添加；要让 Xcode 外部的 Agent 调用 Xcode 工具，则配置 MCP。两种连接都不能代替独立的构建、测试和发布验收。
谁该看这篇：正在 Xcode 27.1 中接入 ACP Agent，并准备拿真实项目验证的 Apple 平台开发者。
谁该看这篇：要判断自研 Agent 如何对接 Xcode 客户端的工具开发者。
谁该看这篇：需要划清 Agent 会话、Xcode 工具调用与 CI 构建职责的研发平台及 CI 工程师。
时效核对：Xcode 27.1 于 2026 年 10 月 15 日发布；本文核对版本状态与接入路径的时间为 2026 年 10 月 17 日。部署前请再查 Apple 的 Xcode 发布记录 和 Xcode 系统要求，不要把测试版说明当成正式版行为。
SECTION 01Apple 平台开发者：先确认 Xcode 与主机是否匹配
Xcode 27.1 的 ACP 接入场景，是在 Xcode 中选择并使用一个符合 Agent Client Protocol 的 Agent。Apple 的编码智能设置将添加入口放在 Xcode > Settings > Intelligence；发布记录确认 Xcode 27.1 于 2026 年 10 月 15 日发布。
先确认运行主机，而不是一看到添加入口就开始配置。对照 Apple 当前系统要求页面中 Xcode 27.1 正式版对应的信息；不要从旧版 Xcode 的经验推算系统兼容性。
| 先核对的项目 | 你要确认什么 | 不匹配时的处理 |
|---|---|---|
| Xcode 版本 | 确认启动的是 Xcode 27.1，而不是另一份并存安装 | 用当前实际启动的版本复核设置入口和组件状态 |
| macOS 与硬件 | 对照 Apple 当前系统要求页面 | 不满足要求就先换兼容主机或系统，不要继续排查 Agent |
| Agent 支持 | Agent 官方文档明确支持 ACP，并说明启动方式 | 没有 ACP 支持说明时，不要把它当作可直接添加的 ACP Agent |
| 项目工作区 | 目标项目或工作区已在 Xcode 打开 | 先打开目标工程，再执行上下文验证 |
场景案例：你在设置中添加 Agent 后能看到它，但它回答的不是当前工作区内容。这个现象不能只记作“连接成功”：Agent 进程可能已经启动，项目访问却仍然不正确。先确认打开的是目标工程，再用一个只读问题要求它定位指定文件或解释一个已知符号；如果答复与项目不符，先停用修改类操作，再查工作目录、访问范围与启动配置。
SECTION 02Agent 工具开发者：把 ACP 初始化与会话分开核验
在 ACP 路径中，Xcode 是客户端，Agent 是接受连接并处理会话的一方。协议兼容是必要条件，但不表示 Agent 的每项能力都已被 Xcode 支持，也不表示配置面板会替你推断它的启动参数。
按 ACP 官方初始化说明，客户端与 Agent 初始化时会协商协议版本、能力和实现信息；之后才进入会话交互。ACP 会话设置说明进一步介绍了建立或恢复会话的阶段。排查时应区分“初始化没完成”和“会话建立后处理任务失败”，不要把两类日志混为一个启动错误。
这里也要避开缩写误判：本文所说的 ACP 是 Agent Client Protocol。名称相近不代表协议、传输方式或客户端角色相同；应以 Agent 官方文档明确列出的协议和版本为准。若文档没有声明支持 Xcode 所使用的 ACP 能力，不要仅凭“支持 Agent 协议”这样的宽泛描述判定兼容。
SECTION 03Xcode 项目维护者：按低风险顺序添加并验证
Apple 文档确认，未出现在内置列表、但支持 ACP 的 Agent，可以从 Intelligence > Agents > Add an Agent 添加。文档只说明需要在随后出现的界面填写信息，并未给出适用于所有 Agent 的统一命令或字段模板；因此启动程序、参数、环境变量和工作目录都应依据 Agent 自己的配置说明及界面实际字段填写。
按以下顺序操作，失败时更容易定位在哪一层：
- 记录环境。写下当前 Xcode 版本、macOS 版本和实际启动的 Xcode 应用位置；与 Apple 的系统要求核对。版本或系统不匹配时，先解决兼容性。
- 确认 Agent 声明。查 Agent 官方文档中的 ACP 支持、安装方式与启动说明。若只有 MCP 配置示例，就不要将该示例填入 ACP 添加面板。
- 打开目标工作区。先在 Xcode 中打开要验证的项目或工作区，并确认当前打开的不是另一个副本。
- 添加并逐项核对。进入 Intelligence 的 Agents 区域，选择添加 Agent；仅填写界面要求且能从 Agent 文档确认的启动信息。遇到文档未解释的字段，先查明含义再保存。
- 先做只读验证。让 Agent 定位一个已知文件、概述指定类型，或回答一个能从项目内容核对的问题；暂不授权它批量修改或运行破坏性命令。
- 分开记录验收结果。分别记下 Agent 是否启动、是否建立会话、是否读到正确项目，以及它能否调用预期能力。连接显示正常不等于工作区访问正确。
- 出现异常就按层回退。不显示时检查兼容声明与设置位置；无法启动时回到 Agent 文档核对启动项；能启动但上下文错误时检查项目是否打开及访问范围。不要靠扩大权限掩盖配置问题。
SECTION 04需要 Xcode 工具的开发者：按入口选择 ACP 或 MCP
| 你的实际目标 | 应选择的通道 | 验证重点 |
|---|---|---|
| 在 Xcode 的编码助手中选择一个兼容 Agent | ACP：在 Xcode 的 Agents 设置中添加 | Agent 能否启动、建立会话并读取当前工作区 |
| 从 Xcode 外部启动 Agent，并调用 Xcode 能力 | MCP：允许外部 Agent 使用 Xcode 工具，并配置客户端连接 | Xcode 中项目是否打开、外部客户端是否连到预期 Xcode 实例 |
| 让 Agent 自动完成 CI 构建或发布 | 不以 ACP/MCP 连接状态作为验收 | 独立运行构建、测试，并检查产物与签名结果 |
Apple 的外部 Agent 使用 Xcode 文档说明，外部 Agent 需要在 Xcode 的 Intelligence 设置中获准使用 Xcode 工具，并通过 Xcode 提供的 MCP 服务配置客户端；该路径不是“把外部 Agent 作为 ACP Agent 加进 Xcode”。
权限提醒：接入前先确定 Agent 能访问哪些项目文件、能运行哪些工具、凭据从哪里读取。只读试验和可写任务应分开授权；不要把开发者密钥、签名凭据或生产令牌直接放进未经审查的启动环境。
SECTION 05研发平台与 CI 工程师：把连接验收和构建验收拆开
ACP 会话成功，只能证明交互链路达到某个阶段；外部 Agent 能调用 Xcode 工具，也不能证明项目能稳定构建、测试通过或产物可发布。Apple 的 Xcode 命令行工具参考说明，xcodebuild 用于构建 Xcode 项目和工作区；Apple 的测试说明介绍了通过命令行运行测试及检查结果包的方式。把这些项目级结果留在 CI 或独立验收任务中记录。
你可以将准入判断写成条件分支：
- 若目标是让 Xcode 内使用 Agent，且 Agent 官方说明支持 ACP，则走 ACP 添加与只读项目验证；否则回退到 Agent 文档确认支持的入口，不要强行套用 ACP。
- 若Agent 从 Xcode 外部启动并需要 Xcode 工具，则走 MCP 配置；否则不要为了“能调用工具”而同时开启不需要的通道。
- 若任务涉及构建、测试或发布，则在 CI 或独立流程运行真实项目验收；否则将结果标记为交互验证，不作为发布证据。
- 若权限边界、凭据来源或远程运行环境尚未确认，则只做低风险试验并限制项目范围；确认后再扩大权限。
平台负责人还应区分远程图形会话、命令行连接与自动化任务的运行条件。远程 Mac 是否能承担该工作，必须以实际交付的 Xcode 版本、系统兼容性、账户权限和你自己的项目验收结果为准；不要从“可 SSH 登录”推断“交互式 Agent、模拟器或 CI 全部可用”。如果你还在规划主机环境，可先看远程 Mac 开发环境入口，并在决定使用前对照当前方案与价格信息核实可用内容。
优缺点要分别看：
- ✅ ACP 适合在 Xcode 内选择和使用兼容 Agent，接入路径清晰。
- ✅ MCP 适合外部 Agent 调用 Xcode 提供的工具，外部客户端可按自身配置接入。
- ⚠️ ACP 兼容不等于能力完全一致；Agent 启动、项目访问与具体工具权限仍需逐项验证。
- ❌ 任何一种连接都不提供 CI 构建通过、测试通过或发布成功的证据。
SECTION 06常见问题
添加后列表里没有 Agent，怎么排查？
先回到 Intelligence 设置的 Agents 区域，确认你使用的是添加 ACP Agent 的入口，并核对 Agent 官方说明是否明确声明 ACP 支持。随后检查 Xcode 与 macOS 是否满足当前 Apple 要求；若入口正确但添加后仍未显示，记录 Xcode 提示和 Agent 启动信息，再按 Agent 文档逐项核对，而不要改用 MCP 参数碰运气。
启动信息应该从哪里取得？
以 Agent 官方文档和 Xcode 添加面板共同为准。文档负责说明 Agent 的启动程序、参数与运行条件，面板负责说明 Xcode 当前要求填写的内容；两者不一致时先确认 Agent 版本及支持方式。不要照搬其他 Agent 的路径，也不要自行添加未被文档解释的环境变量或权限。
Agent 显示已连接，为什么仍然答不对项目问题？
连接状态不能单独证明项目上下文已正确传入。确认目标工程在 Xcode 中打开，再用可在代码中核实的只读任务检查文件与符号访问；若结果不匹配，排查工作区选择、启动目录与文件权限。只有连接状态和上下文验证都通过，才进入受控的修改任务。
外部 Agent 应添加为 ACP Agent 吗？
如果 Agent 在 Xcode 外部启动，目标是调用 Xcode 工具，应按照 Apple 文档配置外部 Agent 使用 Xcode 的 MCP 服务；ACP 添加入口则用于在 Xcode 中配置兼容 Agent。先按 Agent 的运行位置和所需调用方向选择，不要因为两种方案都涉及 Agent，就把它们当成同一条连接链路。
如果你已经确定要在哪个入口使用 Agent，但手头没有符合要求的 macOS 主机，租用真实 Mac 可以避免为短期验证立即购置硬件；不过远程访问会增加网络与账户权限管理，长期稳定的重负载也应与自购设备的持续成本一并比较。下单前先核对 MACNOX 当前远程 Mac 方案页面列出的实际交付信息，再用你的 Xcode 版本、Agent 启动方式和 CI 验收流程做准入测试；如果必须使用本地物理接口或已有长期固定主机，租赁未必适合。