Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (55 loc) · 6.38 KB

AGENTS.md

File metadata and controls

74 lines (55 loc) · 6.38 KB
Raw

AGENTS.md

沟通规则

  1. 直接说明结论，省略反向对比句式。
  2. 永远保持中立、客观和理性。
  3. 永远使用用户视角沟通产品问题。

产品预期与项目事实

判断产品逻辑、交互和 UI 是否符合预期时，按以下顺序判断：

  1. 用户已经明确验收通过的行为
  2. docs/product/ 中的当前需求
  3. docs/architecture/ 中已接受的架构决策
  4. 当前代码与自动化测试所反映的实现现状
  5. README 与历史讨论

自动化测试通过只代表实现满足测试中写明的断言。产品逻辑、交互和 UI 是否符合预期，以用户验收结果为准。

开发、验证与提交

  • 用户明确要求实现或修复，且评估合理、范围清楚时，可修改相应源码和文档；只读或先提建议的任务保持只读。发现矛盾、未决选择或未接受风险时，说明依据并再次确认。
  • 默认验证限于源代码、现有文件、既有日志和不触发构建、依赖安装、测试宿主、预览或 App 运行的文本级检查。改动交给用户验收；测试代码、执行操作和提交仍遵守下述授权与验收要求。
  • 构建、编译、链接、依赖安装或更新、自动化测试、预览、截图检查、交互验收、App 启动或操作都需要用户当前轮明确授权相应操作类别；所有 xcodebuild 操作均受此门禁约束，包括 build、build-for-testing、test、test-without-building 和 -showBuildSettings。
  • “实现”“修复”“继续”“验证”“回归检查”“收尾”“review”“提交前检查”等请求不产生上述执行授权；较早轮次的用户批准、已保存的命令批准、沙箱批准、工具审批或提权批准也不产生用户授权。
  • 授权只覆盖用户说明的类别、scheme、configuration、目标和范围；构建授权不扩展到测试、预览或 App 启动。Skill 和其他工作流同样受此限制。
  • 已授权命令在目标逻辑开始前因测试宿主、Xcode 服务、权限、签名、环境或工具审批失败时立即停止。禁止自行更换 project/workspace、destination、DerivedData、Xcode 路径、命令类型或参数重试；任何重试需要用户当前轮重新明确授权。
  • 产品逻辑、交互和 UI 由用户验收，构建、测试和代理检查不能代替用户验收。
  • 用户验收通过且用户当前轮明确授权测试代码变更后，才可按授权范围为高频主路径、核心状态转换、数据完整性、不可逆操作和高影响故障补充自动化测试；禁止固化未经验收的行为或纯理论场景。
  • 用户明确验收通过后才能提交；未经验收的改动不得提交，也不得与已验收改动混入同一次提交。

交互与 UI 原型

  • 涉及新交互流程、关键页面布局、多状态变化或预期仍有歧义的需求，先制作可操作的 HTML 稿。
  • HTML 稿应覆盖主要操作路径、关键状态、反馈方式和必要的异常状态，并使用接近真实场景的示例数据。
  • HTML 稿完成后交给用户确认；用户明确认可交互和 UI 方向后，再写入正式 AppKit 或 SwiftUI 实现。
  • 用户在 HTML 稿阶段提出的调整应先更新到原型并再次确认，减少正式实现阶段的方向性返工。
  • 简单文案、明确的局部样式修正和用户明确要求直接修改的事项，可以按用户指示进入实现。
  • docs/prototypes/ 下的 HTML 稿统一使用 prototype-shell.css 和 prototype-shell.js 提供左侧原型导航、App menubar、字号令牌与收起行为；禁止在单个页面重复维护这些外壳结构。
  • 新增原型页面时，先按 docs/prototypes/guidelines/index.html 的页面骨架和检查清单实现，再在 prototype-shell.js 的页面登记表中增加入口。
  • 页面专属演示状态通过 prototypePageActions 或 prototypePanelFooter 模板接入共享左栏；产品界面内的操作继续放在模拟 App 窗口中。
  • UI 使用完成任务所需的最小信息表达；每段状态、标题、说明和按钮文案都必须帮助用户判断当前情况或完成下一步。
  • 同一事实不得在状态、标题、说明和按钮中重复表达。
  • 用户文案只描述用户可观察到的状态、下一步操作和操作后果。Bookmark、缓存、持续访问机制等实现概念，只有在会影响用户判断或恢复操作时才显示。
  • FileFacet 本地反例：同一界面同时出现“需授权”“重新授权”“持续访问权限”“重新选择”“重新定位”和“缓存缩略图”，将同一访问问题重复为多套说法，并暴露了用户完成恢复操作无需理解的实现概念。此类界面应保留当前状态、必要定位线索、主要操作及操作后果所需的最小信息。

工程规则

  • 解释文案、防御分支、fallback、辅助状态和抽象必须对应真实可发生的用户场景、已确认需求、已证明故障路径或有文档依据的高影响安全风险。
  • 主窗口、视频网格、标签树、多选、拖拽、菜单和窗口行为使用 AppKit。
  • SwiftUI 只用于设置、引导、身份验证等轻量辅助界面，并通过窄接口接入 AppKit。
  • 数据库使用系统 SQLite3；引入第三方运行时依赖前必须记录架构决策。
  • 默认不发起网络请求，不记录完整文件路径、文件名、标签内容或 Bookmark 数据。
  • 所有扫描、媒体解析和缩略图任务都在后台执行，UI 更新回到 MainActor。
  • 用户视频只读访问；不得移动、重命名、修改或删除原始视频。

参考验证命令

以下命令仅供选择验证范围，不构成执行授权。获得用户当前轮构建授权后，可以运行：

xcodebuild -project VideoTagManager.xcodeproj -scheme VideoTagManager -configuration Debug -derivedDataPath .build/DerivedData build

获得用户当前轮测试授权后，按授权范围运行：

xcodebuild -project VideoTagManager.xcodeproj -scheme VideoTagManager -configuration Debug -derivedDataPath .build/DerivedData test

./script/build_and_run.sh 会停止项目构建实例、构建、处理产物签名并尝试启动 App，须获当前轮对这些操作及目标范围的明确授权。仅获启动授权时，只读核实现有 App 路径后使用单独启动命令。

未授权或因执行失败停止的项目记录为延期验证，汇报拟议命令、未执行原因和剩余风险。