Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (60 loc) · 5.32 KB

AGENTS.md

File metadata and controls

87 lines (60 loc) · 5.32 KB
Raw

AGENTS.md

本文件是 Mos 仓库的通用 agent 入口。Claude、Codex 和其他自动化编码代理都应从这里开始；工具专属入口文件只保留跳转，不复制长指令。

指令优先级

当不同文件或历史记录互相冲突时，按以下顺序执行：

  1. 用户当前请求、系统/工具安全规则。
  2. 本文件 AGENTS.md。
  3. .agents/INDEX.md 指向的专题文档和 .agents/skills/*。
  4. 当前源码、Xcode 工程、test plan、LOCALIZATION.md 等活跃项目文件。
  5. docs/、website/docs/ 中的历史设计、计划、复盘。

历史 plans 只能作为背景材料；构建命令、目录结构、target membership 和测试范围必须以当前工程为准。

启动流程

每个 agent 接手任务时先执行这组轻量索引：

  1. 读本文件。
  2. 读 .agents/INDEX.md，按任务类型进入对应专题文档或 skill。
  3. 检查 git status --short，默认保留用户已有改动。
  4. 只读取与当前任务相关的源码、测试和文档。

不要在 CLAUDE.md、未来的 CODEX.md 或其他工具入口里维护第二份规则；它们应只指向 AGENTS.md。

项目硬约束

  • Mos 是 macOS 菜单栏应用，技术栈是 Swift 5、AppKit、Xcode 工程和 Swift Package Manager。
  • 最低系统版本是 macOS 10.13。新 API 必须有 availability gate 或 fallback。
  • 常规构建和测试使用共享 scheme Debug，不要用 -target Mos 代替。
  • 新增或移动 Swift 文件后，必须确认加入正确的 Mos / MosTests target，并跑一次相关 build 或 test。
  • UI 文案必须本地化；因为最低支持 macOS 10.13，Swift 代码使用 NSLocalizedString(_:comment:)，不要使用 String(localized:)。
  • Logi/HID、Accessibility、签名、notarization、发布和真实设备测试都属于高风险操作，必要时先向用户确认。
  • 危险命令：xcodebuild test 加 CODE_SIGNING_ALLOWED=NO 会把 Mos Debug.app 重签成 adhoc，改变代码签名身份，触发 macOS TCC 重新弹"允许访问"授权窗；若此时有完整 Mos 实例在跑（带全局 CGEvent tap），模态弹窗会占住主线程冻结全部鼠标键盘输入。验证代码优先用纯 xcodebuild build（只编译不启动、不改签名，与 Xcode ⌘B 等价）；确需跑 test 前先 pgrep -fl "Mos Debug.app" 确认无实例在跑，跑完用正常身份重新 build 把 app 签回去。

常用命令

xcodebuild -scheme Debug -configuration Debug -destination 'platform=macOS' build
xcodebuild -scheme Debug -destination 'platform=macOS' test
xcodebuild -scheme Debug -destination 'platform=macOS' test -only-testing:MosTests/<TestClassName>
LOGI_REAL_DEVICE=1 xcodebuild -scheme Debug -testPlan DebugWithDevice -destination 'platform=macOS' test
scripts/qa/lint-logi-boundary.sh

真实设备测试前必须确认 Logi 设备已连接。scripts/qa/lint-logi-boundary.sh 用于守住 Mos/Logi 和 Mos/Integration 的边界。

质量门槛

改动完成前，根据风险选择验证，不要只靠静态阅读宣称通过。最低要求：

  • bugfix 优先补回归测试；无法测试时说明原因和人工验证路径。
  • Swift 逻辑改动至少跑相关 MosTests。
  • Xcode 工程、target membership 或跨模块改动跑 Debug build。
  • Logi/HID 改动跑相关单测，并在涉及边界时跑 scripts/qa/lint-logi-boundary.sh。
  • 准备发布、更新 appcast、签名/notarization 或创建 GitHub release draft 时，必须使用 release-preparation skill，不要自行拼接发布流程。
  • 处理社区 PR（评估/审查/合并/关闭/批量扫描）与发版后回访 issue 时，必须使用 community-pr-loop skill（.agents/skills/community-pr-loop/SKILL.md），不要自行拼接处理流程。

最终汇报只列出已执行的相关验证、与本次改动直接相关但无法执行的验证，以及真实剩余风险。

更完整的测试矩阵和代码质量规则见 .agents/docs/testing.md 与 .agents/docs/quality-gates.md。

人类确认边界

AI 可以辅助实现、测试和整理文档，但这些动作必须由用户明确确认后再做：

  • 发布 GitHub release、推送发布分支、提交 notarization 或签名相关变更。
  • 运行真实设备测试或需要用户本机权限/设备状态的操作。
  • 提交安全报告、批量创建 issue/PR、或替用户对外声明维护结论。
  • 修改会影响旧用户数据读取、更新检测、权限提示或持久化格式的行为。

确认边界不是普通任务的检查清单。只有当高风险动作与当前请求直接相关时，才说明需要用户确认；不要把未请求的高风险流程列为普通提交的剩余风险。

最终交付必须能解释改动原因、验证证据和剩余风险。

发布流程中的 push、publish 和对外可见 release 动作必须单独列为“用户确认后执行”，不要混入 agent 可直接执行的主命令序列。

索引入口

  • .agents/INDEX.md：任务类型到文档/skill 的路由表。
  • .agents/docs/code-map.md：模块地图和边界说明。
  • .agents/docs/testing.md：构建、测试、真实设备和发布验证矩阵。
  • .agents/docs/quality-gates.md：可测试性、热路径、持久化、本地化和发布质量门槛。
  • .agents/skills/README.md：仓库内 agent skills 清单。
  • LOCALIZATION.md：完整本地化指南。