规则越写越长，OpenHands 每次都带着整套 iOS 手册运行，Agent 仍可能漏掉真正需要的 Xcode 验收。
最快解法：持续生效、所有任务都必须看到的短规则放进 AGENTS.md；只在特定任务触发的流程放进 OpenHands Skills；构建、签名和设备验证交给独立的 Mac 门禁。
谁该看这篇：仓库维护者可以用它收敛基础项目约定；移动端开发者可以据此组织 Xcode 和 Swift 专项流程。平台与安全团队则需要重点关注 Skill 的加载顺序、脚本、MCP 工具和敏感路径权限。
最后更新于 2026 年 9 月 8 日，规则依据已核对 OpenHands Skills 官方概览、SDK Skill 指南 与 Apple 的 Xcode 文档。
先按“是否必须始终可见”划分职责
OpenHands Skills 和 AGENTS.md 不是两个互相替代的配置格式，而是两种不同的上下文策略。官方文档把根目录 AGENTS.md 定义为永久仓库上下文，而 SKILL.md 更适合通过描述、触发词或渐进披露，在需要时加载较大规模的专业知识。(docs.openhands.dev)
你可以先用下面的判断：
- 所有任务都必须遵守的规则：放进
AGENTS.md。 - 只有修改 SwiftUI、Core Data、Widget 或某个业务模块时才需要的知识：放进对应 Skill。
- 会改变文件、启动命令、访问网络或读取凭据的内容：不能只当作提示词处理，还要进入脚本和权限审查。
- 最终是否构建成功、测试通过或签名有效：必须由 Mac 环境产生可复核日志，不能以 Agent 的文字报告作为证据。
AGENTS.md 应该回答“这个仓库是什么、不能破坏什么、最小验证是什么”。典型内容包括：
- 仓库目的与主要目录；
- 必须使用的依赖管理方式；
- 基础格式化、静态检查和通用 CI 门禁；
- 修改代码前必须查看的配置文件；
- 不允许触碰的凭据、证书和生产目录；
- 任何任务完成后都要输出的验证结果。
它不适合承载完整的 Swift 并发教程、几十个 xcodebuild 变体，或一份把所有模块都写进去的发布手册。OpenHands 官方也明确提醒，始终加载的旧式完整内容会持续占用后续对话上下文；较大的知识块应考虑使用 SKILL.md 的渐进披露方式。(docs.openhands.dev)
仓库维护者负责 AGENTS.md 的最小公共面
对于 iOS 仓库，AGENTS.md 可以保持在一页左右，但必须是可验证的规则，而不是口号。例如：
# Repository Rules
- This repository contains the iOS application and its shared packages.
- Do not modify signing certificates, provisioning profiles, or secrets.
- Use the package manager and commands already declared by the repository.
- Before changing a target, inspect its .xcodeproj, .xcworkspace, scheme, and test plan.
- Run the repository's documented lint and unit-test checks before opening a PR.
- Report commands, exit codes, changed files, and tests that were not run.
这里的关键不是格式，而是来源。仓库维护者应从现有的 README、CI 工作流、Package.swift、项目文件、共享 Scheme 和测试计划中提炼规则，而不是凭记忆补写一套“理想工程规范”。
Xcode 命令是否应该全部固定在 AGENTS.md 中？
不应该。只把跨任务稳定、且不会因为机器状态变化而失效的入口写进去，例如“使用仓库声明的共享 Scheme 执行测试”。具体的 Scheme 名称、模拟器名称、测试计划和构建参数，最好放进 iOS Skill 或 CI 配置；如果仓库已经有唯一且稳定的命令，也可以在 AGENTS.md 中保留一条最小命令。
Apple 文档说明，Scheme 会决定构建、测试、运行、分析和归档时使用哪些 Target；测试计划还会进一步决定执行哪些测试及其配置。因此，命令不能脱离真实项目文件单独维护。(developer.apple.com)
移动端开发者用 Skills 承载按需的 Apple 流程
一个合适的 iOS Skill 不应只是“请遵循 Swift 最佳实践”，而应当让 OpenHands 能判断什么时候需要调用它，并在调用后完成一组明确动作。
建议将目录组织成：
.agents/
└── skills/
└── ios-validation/
├── SKILL.md
├── references/
│ ├── project-entry.md
│ └── test-matrix.md
└── scripts/
├── inspect-xcode-project.sh
└── run-ios-tests.sh
SKILL.md 的描述要能区分触发场景，例如：
---
name: ios-validation
description: >
Use this skill when changing Swift, SwiftUI, Xcode targets,
test plans, schemes, signing settings, or iOS build commands.
triggers:
- Xcode
- xcodebuild
- simulator
- signing
- test plan
---
正文再写操作顺序，而不是重复 AGENTS.md：
- 识别
.xcworkspace、.xcodeproj和可用 Scheme； - 读取项目实际的最低系统版本和测试目标；
- 检查模拟器或物理设备是否可用；
- 先运行针对性测试，再决定是否执行完整测试计划；
- 保存
.xcresult、构建日志和失败测试名称； - 将未运行的签名或设备测试明确列出。
OpenHands 的 SDK 指南显示，AgentSkills 格式会先让 Agent 看到名称、描述和位置，之后再按需读取完整内容；Skill 还可以发现同目录下的脚本、参考资料和资源文件。描述如果写得过于宽泛，Agent 就无法稳定判断何时加载。(docs.openhands.dev)
Apple 的 xcodebuild test 会生成包含测试结果、覆盖率和日志的 .xcresults 包。对于团队协作，这些结果比“测试已通过”的自然语言总结更适合作为交付物。(developer.apple.com)
Skill 中能否放脚本和参考资料？
可以，但“可以包含”不等于“可以默认信任”。脚本适合封装重复、可审计的检查，例如发现工程入口、列出 Scheme、验证模拟器状态；大型说明、版本差异和测试矩阵则适合放入 references/，由 SKILL.md 指向。
不要在 Skill 中直接保存证书、令牌、私有 API 地址或生产环境路径。若 Skill 会调用动态 Shell 命令、MCP 服务或外部工具，执行权限应按代码处理，而不是按 Markdown 文档处理。OpenHands 文档明确指出，动态命令可能以完整 Shell 权限执行；插件还可以同时携带 Skills、Hooks、MCP 配置、Agents 和 Commands。(docs.openhands.dev)
平台团队必须治理加载顺序和旧 Microagents
截至 2026 年 9 月 8 日核对的官方文档，推荐的项目级 Skills 目录是 .agents/skills/；.openhands/skills/ 与 .openhands/microagents/ 属于兼容或旧路径。多个同名 Skill 存在时，项目目录优先于用户目录，推荐目录也优先于旧目录。
这会带来三个容易被忽略的风险：
- 同名覆盖：用户目录里有一个
ios-validation，项目目录里也有一个同名 Skill，实际加载的内容可能与开发者预期不同。 - 迁移误判：旧 Microagents 文件仍能被部分路径识别，并不代表它是当前首选格式。
- 共享规则漂移：多个仓库复制一份组织级 Skill 后，各自修改触发词和脚本，最终无法判断哪一版才是标准。
旧 Microagents 是否需要迁移，不能只看目录名称或文件是否仍能被读取。新建内容应直接使用 .agents/skills/<name>/SKILL.md；已经依赖旧路径的仓库，则应先保留回退路径，再用同一个低风险任务比较迁移前后的实际加载结果。
迁移优先级可以这样定：
- 新建内容直接使用
.agents/skills/<name>/SKILL.md； - 旧 Microagents 只保留尚未完成验证的兼容内容；
- 每个共享 Skill 标记版本、所有者和变更审查人；
- 用
/skills或等效诊断方式确认当前会话看到的 Skills； - 对同一个任务记录加载列表、触发结果、实际执行命令和最终差异。
旧版 OpenHands 仓库说明中仍能看到 V0 的 Microagents 与 V1 的 Skills 术语并存，这说明兼容状态和产品当前推荐方向不能混为一谈。迁移判断应以当前官方文档和实际加载结果为准，而不是只看旧目录是否还能工作。
安全团队审查“可执行的 Skill”，而不是只审 Markdown
安全评审至少要覆盖以下对象：
SKILL.md中的动态命令和环境变量；scripts/下脚本的执行权限、参数拼接和路径处理；references/是否意外包含内部域名、密钥格式或敏感样例；- MCP Server 是否能访问网络、文件系统或凭据；
- Hook 是否能阻断危险操作，还是只做异步记录；
- 脚本是否允许 Agent 将用户输入直接传给 Shell。
尤其要区分“提示上下文”和“执行安全边界”。一句“不要修改签名文件”只是模型指令，不是文件系统保护；一个 run-ios-tests.sh 如果拥有读取钥匙串、修改工程文件或上传构建产物的权限，就需要像普通 CI 脚本一样经过代码审查。
OpenHands 的 Hook 文档指出，同步 Hook 可以参与阻断，而异步 Hook 不能阻止操作，更适合日志或遥测；官方还建议通过实际输入测试脚本并检查退出码。(docs.openhands.dev)
发布负责人把 Agent 结果交给 Mac 门禁
OpenHands 完成代码修改后，交接物至少应包括：
- 补丁或提交哈希；
- 修改文件和依赖变化；
- 使用过的 Skill 名称及版本；
- 执行过的命令、退出码和日志位置；
- 已运行、失败和未运行的测试；
- 是否涉及签名、证书、设备或发布权限；
- 需要人工确认的风险项。
Mac 门禁应拆成不同风险层级：
- 静态层：格式化、Lint、依赖锁文件和危险文件变更检查；
- 构建层：使用真实 Scheme 执行 Debug 或 Release 构建；
- 模拟器测试层：运行指定测试计划并保留
.xcresult； - 签名层：确认 Team、Bundle ID、Provisioning Profile 和证书状态；
- 设备层：在目标物理设备上验证安装、启动、权限和关键流程；
- 发布层：将归档、导出和上传权限与普通代码修改分离。
Apple 的设备运行文档显示，物理设备测试涉及开发者账号、Team、唯一 Bundle ID 和签名设置，这些并不是一段 Skill 文本能够替代的环境事实。(developer.apple.com)
iOS 仓库规则分层评分
| 方案 | 始终可见性 | 上下文成本 | 适合内容 | iOS 验收能力 | 推荐评分 |
|---|---|---|---|---|---|
全部写入 AGENTS.md |
高 | 高 | 公共约定、目录、基础门禁 | 低 | 6/10 |
| 全部写入 Skills | 中 | 低至中 | 专项流程、框架知识、参考资料 | 中 | 7/10 |
AGENTS.md + iOS Skills + Mac 门禁 |
高 | 可控 | 分层规则、按需知识、真实验证 | 高 | 9/10 |
| 继续使用旧 Microagents 为主 | 不稳定 | 不确定 | 迁移过渡 | 低至中 | 4/10 |
迁移前的可勾选验收清单
- [ ]
AGENTS.md只保留所有任务都需要的规则，并能从仓库文件或 CI 中验证。 - [ ] iOS 专项流程已拆成独立
SKILL.md，描述中包含明确触发条件。 - [ ] Skill 没有复制与
AGENTS.md冲突的基础命令或权限要求。 - [ ]
.agents/skills/、用户级目录和旧 Microagents 的同名规则已完成加载结果对比。 - [ ] Skill 中的脚本、动态命令和 MCP 配置已由安全团队审查。
- [ ] Xcode Scheme、测试计划、模拟器目标和构建命令来自真实项目或 CI 配置。
- [ ] Mac 门禁会保存构建日志、
.xcresult、签名状态和未运行测试。 - [ ] Agent 的“已完成”描述不会直接替代构建、测试、签名或设备证据。
- [ ] 已用一个低风险 iOS 任务验证迁移前后的差异，再扩大到核心业务模块。
如果你需要把 Xcode 验收拆到独立机器上，先确认仓库是否需要物理设备、专用证书或持续占用的模拟器；这类条件决定了远程 Mac 工作区是否合适。你也可以先阅读 SSHMac 的帮助中心，再结合 Mac mini 租赁方案评估连接方式、权限边界和团队使用模式。
当前本地方案与 Mac 验收方案的取舍
如果你现在依赖开发者个人 Mac，常见问题是机器被长时间占用、Xcode 版本和模拟器状态不一致，以及签名证书只存在于某个人的钥匙串中。若改用普通 Linux 或 Windows 环境，OpenHands 可以完成部分文本修改和静态检查，却无法自然覆盖真实的 Xcode 构建、Apple 签名和物理设备验证。
因此，最稳妥的做法不是把所有权限塞给 Agent，而是让规则负责指导、让 Mac 门禁负责证明。若你只需要短期测试 OpenHands 的 iOS 修改流程，SSHMac 提供独立 Mac 工作区会比长期占用个人开发机更容易隔离；但如果你的团队需要持续高负载构建、固定物理接口或完全自主管理证书，直接自购并维护 Mac 仍可能更合适。