Skip to content

AGENTS.md

Latest commit

 

History

History
251 lines (188 loc) · 31.6 KB

AGENTS.md

File metadata and controls

251 lines (188 loc) · 31.6 KB
Raw

仓库开发规则

规范层级与文档边界

G-DOC.entry=DOCUMENTATION.md
G-DOC.authority=chinese
  • 本文件只定义全仓不可绕过的治理门禁和各专项规范的入口，不替代专项文件中的完整步骤。
  • 分支、worktree、提交、PR 与合并以 BRANCH_MANAGEMENT.md 为唯一流程规范；新功能开发以 FEATURE_DEVELOPMENT.md 为流程入口；文件命名、日志、发布和 macOS 设计分别以 FILE_NAMING.md、LOGGING.md、RELEASING.md 和中文 design-qa.md 为专项权威。
  • 功能目录中的 PRODUCT_SPEC.md 定义该功能的产品行为，平台附件只能映射平台差异。跨硬件共同语义由 Testing/HardwareCompatibilityContract.md 和 Testing/HardwareVoiceAudioContract.md 定义：前者拥有设备身份、能力、按键与触摸等一致性边界，后者拥有语音音频低延迟、完整性和会话隔离边界；它们不能覆盖具体功能流程，也不能被普通测试手册降低。
  • 除上述两份跨平台合同外，根目录 Testing/ 手册只定义验证方法和通过/失败证据，不得反向新增、覆盖或降低产品规则。TODO.md、Bugs/、功能 README、feature/*/development.md、feature/*/testing.md 以及带日期、版本号或候选分支的段落属于计划或历史证据，不是现行规范；它们与权威规范冲突时必须更新或明确标记为历史，不得据此改变产品行为。
  • 同一层级出现冲突时，先核对 Git 历史、当前实现和适用范围，采用更新且更合理的规则，并在同一个独立治理 PR 中同步所有受影响文档和静态检查。不得仅以“更严格”为由长期保留无法同时执行的互斥规则。
  • 开发者和自动化 Agent 的稳定文档入口是 DOCUMENTATION.md；面向普通用户的 README.md 底部只保留一个指向该入口的链接，不展开规范和测试清单。英文翻译不得独立产生规则；与中文权威文本不一致时以中文为准，并必须修正翻译。

新功能开发规范

  • 开发任何新功能前，必须完整阅读并遵守 FEATURE_DEVELOPMENT.md。该规范适用于仓库作者、维护者、外部贡献者、自动化 Agent 和受委托开发者，不因身份而豁免。
  • 新功能必须从最新 origin/main 开始，开发前扫描全部 Open PR 的标题和标签，再详细检查相关候选完成查重；UI 变更 PR 必须在 PR 附件或持久链接中附实际运行截图，图片字节不入仓库，规则见 截图与设计稿归档规范；任何方案都不得读取或依赖第三方 App 的私有文件、数据或协议。
  • 新功能 PR 必须完成 PR 提交模板 中的检查项，并同时遵守 BRANCH_MANAGEMENT.md 与本文件的专项门禁。

SwiftPM 本地凭据边界

  • 在 macOS 本地运行本仓库的 swift build、swift test 或 swift package resolve 时，必须传入 --disable-keychain；GitHub 源码依赖继续使用现有 Git 凭据助手，公开二进制依赖不得扫描登录钥匙串。
  • 新增或修改调用 SwiftPM 的本地脚本时必须保留该参数。GitHub Actions 等没有交互式登录钥匙串的隔离 CI 环境可按其现有凭据配置执行。

私有依赖与公开构建边界

私有组件来自私有仓库 GetSayAll/sayall-private-platform；本仓库是公开仓库，下列四条不可绕过，细则见私有仓 docs/release/packaging-governance.md 第 2 节第 5–8 条。

  1. 打包基线是最新 origin/main：对外候选（Preview / Stable）只从 git fetch origin main 之后的精确 origin/main SHA 构建，Hotfix 按 RELEASING.md 的例外走 origin/hotfix/vX.Y.Z。本地测试包可以从任意分支或工作树打包，但它不携带版本身份、不得上传 Release、不得作为分发候选。
  2. 私有实现不得进入本仓库：私有平台的源码、XCFramework 二进制、.swiftinterface、构建日志、私有打包脚本，不得提交到本仓库，也不得进入本仓库的 CI Artifact 或 Release。允许存在的只有接入所需的最小引用——模块名与公开 API 的调用（#if canImport(SayAll…) 门控），以及清单里的版本标识（config/release-dependencies.json）、摘要与校验脚本；内部符号、私有文件路径不得写进公开代码、注释或日志。
  3. 没有私有读取权限也必须能编过：任何 PR 都不得让 SAYALL_PRIVATE_PLATFORM_MODE=public 下的 swift build、swift test 失败。缺私有组件时走公开兼容层并标为 public 包；官方发布反过来不得回退到兼容层，缺件即停。
  4. 私有依赖只认私有仓发布的 Tag：Tag 与 XCFramework 由私有仓在维护者本机产出，不依赖任何 CI Artifact。本仓库按清单版本解析 Tag、校验其为 origin/main 祖先并核对构件摘要；私有仓 workflow 的产物（含其 artifact）一律不构成依赖来源，该 workflow 全部未执行也不影响判定。

产品命名规范

  • 英文产品名统一为 SayAll，不得使用 Remote Mic、Wireless Mic 或 SayAll Wireless Mic 作为产品名。
  • 中文产品名统一为「无线麦 SayAll」，保留“无线麦”和“SayAll”之间的半角空格。
  • 中文宣传文案中的产品称呼统一为「无线麦 SayAll App」；英文宣传文案使用 SayAll App。
  • 上述规则适用于普通用户可见的页面、按钮、提示、错误、权限说明、辅助功能标签、帮助、版本说明和宣传内容；完整规则见 design-qa.md 的产品命名与宣传文案。
  • 历史路径、代码标识符、Bundle ID、可执行文件、协议、数据键、安装器和发布资产保持兼容；引用 Remote Mic.app 等真实旧名称时必须保留准确字面值，不得因文案统一改动这些技术边界。

文件命名规范

  • 新增或重命名文件、目录前，必须阅读并遵守 FILE_NAMING.md。
  • 文件语义按完整仓库相对路径判断：目录负责领域或功能作用域，文件名负责角色、对象或变体；不得只看 basename，也不得重复父目录已经表达的作用域。
  • 不得仅为形式统一批量重命名历史文件；公开链接、构建脚本、Bundle、发布资产、外部协议和系统约定名称优先保持兼容。

临时测试工具入库边界

G-TOOL.temporary=forbidden
G-TOOL.testing-executable=forbidden
G-TOOL.permanent-helper=declared-purpose
  • 临时现场探针、手工蓝牙/HID/音频 trace、一次性日志采集脚本、专用实验包构建脚本及其启动器不得新增、恢复或改名后进入版本控制；这项限制按用途判断，不因使用 .sh、.command、Swift 或其他语言而豁免。此类工具只保留在仓库外的本地工作目录，不得作为 CI 或用户测试流程的必需入口。
  • Testing/ 用于长期维护的 Markdown 测试手册、合同和可审计证据，不得新增或恢复可执行辅助文件。现有未列入清理范围的历史文件不因本规则自动删除，也不能作为新增临时工具的先例。
  • 正常产品源码、Tests/ 中的长期自动化回归，以及产品构建、安装、签名、公证和统一发布检查不受禁止；新增可执行工程辅助文件必须说明长期职责及现有入口无法承载的原因，不能把临时工具换目录或扩展名后伪装成正式回归。
  • scripts/verify-repository-governance.sh 拒绝新增 Testing/ 可执行文件和恢复已移除的六个入口；其他新增工程辅助文件必须在 PR 中确认用途边界。仅修改手工工具不应触发产品构建，但分类豁免不是临时工具入库许可。

本地测试包

  • 本地测试包固定命名 SayAll.app，优先替换 ~/Applications/SayAll.app；替换失败才放 ~/Downloads/SayAll-test/SayAll.app。
  • 每次构建必须递增 CFBundleVersion：取 /Applications/SayAll.app、~/Applications/SayAll.app、状态文件 ~/.sayall-local-build 三者最大值 +1，写入本地包的 Info.plist；仓库 Resources/Info.plist 的模板值不得改动。
  • 打包统一走本仓 scripts/package-local-test-app.sh，不得手拼命令。该脚本入库、随仓库分发，已包含 release 构建、组装、递增构建号、ad-hoc 签名、先退出占锁实例再替换与启动。
  • 脚本要求 SAYALL_PRIVATE_SOURCE_ROOT 指向私有仓工作区根目录；缺私有组件时脚本直接报错退出，不会产出缺件的包。
  • 本地包是测试产物：必须如实记录 source_commit 与是否 dirty，不得冒用 Tag，不得作为分发候选。

截图与设计稿归档规范

G-EVIDENCE.screenshots=pr-attachment-or-persistent-link
G-EVIDENCE.design-drafts=external-with-index
G-EVIDENCE.index=manifest-json
G-EVIDENCE.history=retained-no-rewrite
G-EVIDENCE.exception=commit-marker
G-EVIDENCE.build-assets=exempt
  • 截图、设计稿、UI 方案图、视觉对比图和界面录制属于视觉证据，其文件字节不进入版本控制；本仓库只保留可审计的文本索引。构建必需资源按下方例外条目处理。
  • 生产 UI 实际运行截图必须附在 PR 描述或评论中：直接上传为 GitHub 图片附件，或使用他人可访问的持久链接。只提供本地路径、会话内临时图片、工具返回预览或缓存目录不算完成。
  • 设计稿、方案图和视觉对比图同样使用外部证据：评审时用本地绝对路径或可访问链接展示，原始字节保存在仓库外的持久目录，并按用途归档。展示前必须验证格式、像素尺寸和 SHA-256；只有原件与索引都校验通过，才能对用户表述为“已提供设计稿”。
  • 每个证据批次在仓库内只保留一个 manifest.json 索引，沿用 Screenshots/<batch>/manifest.json 的既有惯例：记录批次标识、日期、用途或对应 PR、存储方式，以及逐项的 file、format、width、height、sha256 和外部证据 URL。索引是权威可审计记录；外部链接失效时以索引中的尺寸和 SHA-256 核对原件，不得据此推断当前实现。
  • 如果设计稿来自当前或历史会话，必须优先取回并保存原始字节，不得用截图、重绘、缩放、重新压缩或再次生成替代；原始载荷确实无法取得时，必须明确说明限制，再决定是否重新生成。
  • 构建必需资源不受本规则限制：Resources/AppIcon*、Resources/AppIcons/、Resources/Onboarding/、Resources/Fonts/、状态图标模板，以及 Sources/、Tests/、packaging/ 中被代码、测试或打包脚本直接引用的资源。新增这类资源仍须遵守 BRANCH_MANAGEMENT.md 的大文件门禁。
  • 已入库的历史截图和设计稿按历史证据保留：不因本规则删除，也不重写 Git 历史。移出仓库或压缩存量属于独立清理工作项，必须先取得用户单独授权。
  • scripts/verify-repository-governance.sh 拒绝在 Screenshots/、Design/ 等非构建位置新增位图和视频文件。确需在单个 PR 入库时，必须在提交信息中包含 [visual-evidence-exception]，并在 PR 正文记录路径、用途、批准来源和总大小。

TODO 同步

  • 开发或完成新功能时，必须检查 TODO.md 是否存在对应条目。
  • 如果存在对应条目，必须在同一次修改中同步更新其完成状态和必要说明。
  • 只有功能实现并完成相应验证后，才能将条目标记为完成。

分支与提交管理

  • 分支、worktree、独立提交、Preview staging 和大文件提交门禁统一见 BRANCH_MANAGEMENT.md。
  • 涉及分支创建、切换、commit、合并、Push 或发布前，必须先读取并遵守该文件。

任务范围与等待治理

G-SCOPE.query=read-only
G-SCOPE.unrelated=separate
G-WAIT.mode=bounded
G-CI.reference=BRANCH_MANAGEMENT.md
  • 分析、审查、诊断或状态查询默认只做只读检查并给出证据和结论，不自动扩大为实现、加固、发布或外部状态变更；用户同时要求分析和实施时，必须先说明目标、改动范围和明确不做事项，再开始修改。
  • 当前任务之外的优化、重构、规范调整或历史清理必须拆成独立工作项，不得以“顺手修改”“配套修改”或减少冲突为由静默扩大当前范围。
  • 使用受委托任务时，连续 2 分钟没有工具活动、消息或可验证进展必须主动检查；满 3 分钟仍无进展时应中断并接管或重新委派。CI 或受委托任务已经结束时，应及时回报，不得等待下一次用户追问。
  • 禁止使用无法可靠收回控制权的交互式 CI 等待命令。应使用单次状态查询或产品提供的有界等待机制，轮询间隔保持 30–60 秒，并在等待前声明截止时间；达到截止时间后立即报告当前阶段和已耗时，不得无限等待或无提示自动重试。
  • 普通非发布任务默认在必需 PR 检查通过并完成普通合并后交付；用户明确要求“不用等 CI”或“跳过 CI”时，按 BRANCH_MANAGEMENT.md 的“用户明确授权的 CI 例外”执行；合并后的 main CI 默认作为异步确认，但必须保留可审计结果并在失败时回报。默认在修改 CI 门禁、共享发布脚本或用户明确要求验证 main 时等待对应 main 检查通过；当前任务有明确 CI 例外且用户未要求验证 main 时可免等待，并列明未验证项。
  • 真实发布必须完成适用的签名、公证、真实 UI、公开字节、更新链路和来源验证后才能报告完成；本地构建、单元测试、workflow 已启动或 artifact 已上传都不能替代最终发布结果。

跨应用数据访问边界

  • 禁止读取、解析、解密、复制或依赖其他 App 的内部文件、数据库、沙盒容器、历史记录、私有运行库、私有协议或未公开数据格式。
  • 禁止通过独立 Helper、动态库加载、直接访问 ~/Library / App bundle 内部路径或其他绕过方式规避该限制；其他 App 集成只能使用公开 API、公开协议、用户可见的辅助功能界面或用户明确选择的文件。
  • 创建或更新 PR 前必须检查变更是否触及上述边界；一旦发现，必须停止创建或合入 PR，并拆除相关实现。自动化测试、模拟数据、签名包或用户授权都不能把读取其他 App 内部文件变成允许行为。

语音键响应与手势边界

  • 语音键是实时语音输入主路径，只支持既定的按下/释放会话生命周期；不得把双击或“长按动作”作为语音键的额外触发器，也不得引入与语音输入无关的隐式附加功能。
  • 长按仅表示按住语音键以维持当前语音会话，不得等待长按阈值后才开始语音；语音键按下后必须尽快进入会话，释放后必须尽快结束会话，不得因手势识别延迟、吞掉或重排事件。
  • 语音键路径不得使用双击等待窗口或长按判定计时器来决定主语音动作。任何短按定位输入框、双击、长按动作或其他附加需求，若会增加首个响应延迟、改变默认语音映射或影响连续录音，必须停止实现并先提交独立产品需求与验证，不得作为“顺手修改”合入。
  • 聚焦前台 App 输入框不得绑定到语音键的短按、双击或长按；该能力只能作为普通遥控器按键的独立“聚焦输入框”自定义动作提供，并且必须保持非重复、即时执行，不得读取输入内容。
  • 涉及语音键的 PR 必须验证极速按下/释放响应、连续语音会话和异常中断恢复；若无法证明没有响应回退，不得创建或合入 PR。

跨硬件语音音频完整性规范

  • 这是所有当前及未来硬件的产品硬性规范：语音按下后必须尽快进入真实收音路径，首个有效音频/首字不得因双击窗口、长按阈值、无必要的 debounce、目标切换或排队等待而延迟；实现必须测量并记录从硬件按下到首个有效 PCM 以及可观察首字的耗时。
  • 正常松键不得丢失尾音或尾字。不得直接 flush、清空、丢弃或截断仍在途的音频缓存来换取更快结束；必须保留有序的在途数据，等待采集尾包、主线程投递和输出队列自然完成。
  • 音频背压、重采样、解码、设备切换和会话切换都必须优先保持完整性与顺序。若异常只能强制终止，必须显式记录 completion=forced、中断样本数和原因；不得把异常丢失伪装成正常成功。
  • 每种新硬件交付前必须覆盖首字低延迟、正常松键尾字完整、快速连续会话、断连/取消/超时恢复和跨硬件切换；模拟硬件、单元测试或“队列已入队”不能替代真实设备与目标语音工具验收。
  • 违反“首字快、尾字全、正常不 flush”任一项时，不得将该硬件标记为兼容、推荐或发布候选。

跨平台硬件功能一致性规范

  • 新增或修改任何硬件适配器时，必须检查并遵守 Testing/HardwareCompatibilityContract.md。该合同同时约束 macOS 与 Windows 的设备身份、能力声明、按键边沿、手势、按住连发、连续快速按、语音与触摸互斥、App 切换器、多设备隔离、异常清理、日志和实机矩阵。
  • 平台可以使用不同 API、驱动和虚拟麦克风，但用户可观察语义必须一致；平台或硬件缺少能力时必须明确显示不支持或未知，不得静默替换成含义不同的动作、电脑麦克风或虚假状态。
  • 每次接入新型号都必须在设备测试手册中列出与现有硬件相比的“已对齐、物理不存在、平台不支持、待验证”四类差异，并分别记录 macOS 与 Windows 的自动化、真实设备和最终用户流程结果。
  • 未完成合同规定的对应平台实机矩阵时，只能称为候选，不得因另一个平台、另一个型号、模拟器、单元测试、构建或签名通过而宣称兼容。

新功能测试手册

  • 面向用户的全新功能在交付测试包前，必须在 Testing/ 下新增或更新对应的 Markdown 测试手册；纯内部重构且没有用户可观察行为变化时可不新增。
  • 测试手册至少包含：适用版本或分支、测试前准备、逐步操作、每一步的预期结果、明确的失败判定、稳定功能回归项、日志收集方式，以及自动化、代理实测和用户实测的验证边界。
  • 涉及第三方 APP、真实遥控器、蓝牙、音频、系统权限或不同前后台状态时，必须把这些状态拆成独立用例，不能只写“功能正常”或只提供单元测试结果。
  • 功能行为变化时必须在同一次修改中同步更新测试手册。向用户交付时必须同时提供测试包路径和测试手册链接，并明确哪些用例尚未完成真实环境验收。

Onboarding 产品规范门禁

  • 检查、设计、修改或测试 Onboarding 前，必须先完整阅读 feature/first-run-onboarding/PRODUCT_SPEC.md 及当前平台附件；macOS 使用 platform-macos.md，Windows 使用 platform-windows.md。
  • PRODUCT_SPEC.md 是跨平台产品行为的唯一权威入口。产品不变量发生变化时，必须在同一次修改中同步更新规范、平台附件、实现、测试手册和完整流程截图证据。
  • 平台附件只描述权限、按键、音频、连接和 UI 的平台映射，不能覆盖或降低跨平台的真实连接、真实音频、真实文字、失败恢复、诊断和隐私门槛。
  • Onboarding 验证按下方回归门禁选择范围。流程或能力变化必须验证完整用户旅程及受影响分支。单元测试、截图、模拟设备和构建只能证明各自边界，不能替代真实权限、设备、音频路线和第三方语音工具文字上屏。

日志规范

  • 新增功能、修改功能或修复 Bug 时，必须同时遵守 LOGGING.md，为从请求入口到最终用户结果的完整逻辑链路补齐可关联、可去重、可归因的脱敏日志。
  • 日志不得包含用户内容、个人信息、设备身份、路径、凭据或第三方 App 私有状态；无法观察的外部状态必须明确记录为未知和诊断边界，不得把推测写成事实。
  • PR 交付前必须验证成功、失败、取消、超时、重试和恢复等受影响路径的日志，并确认收到、解码、入队或异步提交不被误记为最终功能成功。

Onboarding 改动回归门禁

G-ONBOARD.validation=risk-based
G-ONBOARD.manifest=production
G-ONBOARD.real-acceptance=retained
  • 修改 Onboarding 时必须更新 Testing/FirstRunOnboarding.md 的验证范围和结果。验证分为两类：
    • 流程、能力门禁、权限、连接、音频、持久化或共享布局变化：执行流程自动化、完整页面截图、构建和受影响的真实旅程验收。
    • 纯文案、本地化、非行为诊断字段或局部截图渲染变化：验证受影响页面和状态，覆盖中英文、浅色和深色；检查生产清单一致性，并执行相关静态检查或定向测试。涉及可执行代码时执行构建；纯文档改动只做文档检查。无法证明影响局限于此时，按第一类执行。
  • 截图使用生产 OnboardingView 的隐藏离屏入口。页面来源是 Sources/RemoteMic/OnboardingScreenshotRenderer.swift 的 pages(for:)；来源、语言、外观和附加状态矩阵见 Testing/FirstRunOnboarding.md。数量按当前构建清单推导，不把历史固定数量当作门禁。页面或场景增删时，在同一 PR 更新对应清单和手册。
  • 完整验证覆盖当前构建实际启用的所有控制来源。定向验证覆盖所有受影响来源、工具和状态。每张 PNG 都要查看窗口 chrome、标题、导航、状态卡、右栏、裁切、对比度和中文字号，并记录格式、尺寸及 SHA-256。
  • 流程回归覆盖首次进入、退出续接、从关于页重跑、返回导航、缺失条件阻断、完成后进入设置及旧配置保留。涉及语音键时，必须覆盖 Fn 按下/释放低延迟、连续会话和异常恢复。
  • 截图只证明静态 UI。产品行为变化仍须完成适用的真实权限、蓝牙、音频、遥控器和文字上屏验收；纯文案验证不扩大为无关硬件验收，也不能把旧现场结果当作新行为的证据。
  • PR 描述分别列出验证分类及理由、自动化、离屏截图、构建/CI、真实设备/第三方工具结果和未覆盖边界，并附可审计截图证据。

界面设计硬性约束

  • 中文界面文字的最终显示字号不得小于 12pt；不得通过 minimumScaleFactor 把中文缩小到 12pt 以下。空间不足时应优先调整布局、换行、截断或扩大控件。
  • 尽量不使用下拉列表，尤其不得把大量不同类别的动作混在一个长下拉列表中。选项较多时应按语义分组，并优先使用页面内的分区、按钮网格或分段选择。
  • 优先在页面内完成主要任务和相关设置。高频主流程、关键状态和错误必须持续可见。短时选择、次要编辑和系统原生操作可以使用 Popover 或 Sheet，但必须可取消、支持键盘和辅助功能，并保留当前上下文；不得用连续浮层隐藏必需操作。
  • macOS 界面修改必须同时检查并遵守 design-qa.md 中的设计规范。

Bug 修复固定流程

G-BUG.investigation=evidence-driven
G-BUG.fix=confirmed-cause
G-BUG.real-acceptance=retained
  • 非简单 Bug 采用证据驱动流程：确认错误证据 → 调查日志和代码 → 验证根因假设 → 最小修复 → 验证原始用例及稳定基线。调查阶段可以交替查看代码、日志和实验结果，不要求先取得现场设备才能读代码。
  • 错误证据可以来自现场复现、已有脱敏日志、能失败的回归测试或最小实验。记录触发条件、错误行为、正常边界和证据来源；缺少设备或日志时，明确标记缺口。
  • 正式修复前必须核对可用日志中的事件顺序和最终结果，并用可重复证据确认根因。没有可用日志时，记录原因，使用失败测试或最小实验验证；不得只凭代码猜测提交正式修复。
  • 收到事件、解码或入队不等于最终成功。修复只覆盖已确认根因；验证应使同一错误用例从失败变为通过，并覆盖受影响的稳定基线。
  • 模拟硬件、单元测试、构建、签名和安装包校验只证明各自边界。缺少真实设备或用户流程验收时，交付必须标记为候选或待现场验证；不得声称真机验收完成。发布前仍须完成适用的真实环境验收。
  • 每个 Bug 的证据、日志结论或缺口、根因实验、修复、验证命令和自动化/真机边界都记录到 Bugs/ 下的独立文档。

用户反馈检查规则

  • 当用户提到“用户反馈”“feedback”“用户问题”“用户用不了”或同类现场反馈时，默认只执行只读诊断：先检查相关代码、配置、测试和已有文档，判断反馈描述的问题是否在当前实现中真实存在；这类请求本身不授权修改代码。
  • 除非用户随后明确要求修复或修改，否则不得编辑业务代码、测试、配置或文档，也不得把推测当成已确认问题。证据不足时必须明确说明当前只能确认什么、不能确认什么，以及还需要哪些复现条件、日志或真机验证。
  • 回复必须同时包含两部分：第一部分是可直接转发给普通用户的答复，使用通俗语言说明现象、结论和建议；第二部分是技术详情，列出检查过的代码位置、证据、根因假设、置信度和验证边界。

macOS 私有 Draft 安装包门禁

  • 私有 GitHub Draft 只是分发范围受限，不降低安装包信任要求；任何提供给用户安装的 App、DMG、PKG 或包含这些内容的 ZIP 都必须走项目原生 Developer ID 签名与 Apple 公证流程，禁止上传 ad-hoc、未公证或未 staple 的内部包。
  • 上传前和从私有 Draft 重新下载后，都必须验证 Developer ID Application / Installer、预期 Team ID L3QHLDRPAY、Hardened Runtime、嵌套组件 codesign --deep --strict、stapler validate 和 spctl Gatekeeper；ZIP 必须解压验证内部 App/DMG/PKG，不能只校验 ZIP 摘要。
  • GitHub 远端摘要、重新下载后的 SHA-256 和逐字节比较必须同时通过，才允许清理旧 Draft。任一签名、公证、下载或摘要检查失败时保留现有 Draft，不得降级为 ad-hoc 重试。
  • 签名和公证仍由受保护 Environment、隔离临时 Keychain 或既有无交互发布机承载；不得在日志、Release Notes、仓库或聊天中打印、复制或持久化证书、私钥、密码、P8、notary 凭据和 Token。验证脚本只消费最终资产与非秘密 Team ID，不负责生成签名。
  • 非 macOS 私有 Draft 资产不适用 Apple 门禁。完整流程见 RELEASING.md。

macOS Feature Flag 与预览版回归门禁

  • Feature Flag 默认关闭不等于风险已隔离。只要实验功能改动了共享蓝牙协议、状态机、音频、HID、持久化或页面容器，必须验证开关缺失/默认关闭、明确关闭、开启、使用后再关闭四种状态。
  • 开关缺失或关闭时，现有稳定功能必须与上一正式版行为等价；测试必须覆盖真实协议事件顺序，不能只验证命令字节、设置持久化、Picker 显隐或辅助函数。
  • RC003 普通语音基线路径必须覆盖无需前置主动 MIC_OPEN 的 STREAM_START → AUDIO → STREAM_STOP。修改共享 ATVV 处理后，如果单元测试无法真实驱动 CoreBluetooth 回调，必须使用可注入事件回放或完成 RC003 真机基线验证，并明确记录自动化缺口。
  • 核心语音功能涉及多个组件时，必须增加连续用户旅程测试，而不能只分别测试“动作已提交”“输入框聚焦成功”“Fn 会话成功”或“音频已入队”。至少覆盖“执行 App/快捷键动作 → 目标延迟就绪 → 第一次 STREAM_START → AUDIO → STREAM_STOP → 最终只产生一组正确 Fn 与完整音频”；第二次或第三次才成功必须判定为失败。
  • MIC_EXTEND 能突破 RC003 约 60 秒限制在真机长录音通过前只能称为 ATVV 租期假设；模拟硬件只能验证保活策略，不能证明实际固件接受该命令。
  • macOS 设置页面内容或容器发生变化时，必须在生产窗口允许的最小尺寸逐一点击全部受影响的侧边栏入口，确认导航项、页头、主要控件和滚动均未裁切或改变窗口几何。当前生产最小尺寸为 1020 × 772；800 × 650 只作为离屏截图 harness 的窄宽压力检查，不得表述为真实生产窗口验收。
  • 单元测试、构建、签名、公证和安装包校验通过，只能证明各自检查项通过，不能替代稳定行为验收。稳定基线未验证时，不得发布 Pre-release；实验功能本身可以保持“验证中”。
  • Mac 预览版发布后必须下载公开稳定版归档，并通过固定候选 appcast 执行一次真实 Sparkle 安装更新，不能只运行 --probe。更新后必须验证版本、签名、公证、Sparkle helper 权限与链接、启动/再次启动以及无新增崩溃报告。
  • 预览版必须保持 Pre-release，固定候选 feed 不得改变稳定 feed；发布和验证期间 releases/latest 必须继续指向当前稳定版。

研究与计划文档存放

  • 本项目的详细 research、plan、竞品分析、产品调研、可行性研究和长期实施方案统一写入私有仓库 HD838A/private-marketing-toolkit，本地路径为 /path/to/user-home/Develop/Src/AISrc/marketing。
  • 文档存放到私有仓库 projects/remote-mic-app/ 下的对应工作流和版本目录。目录结构以私有仓库的 AGENTS.md 为准；本仓库不重复定义主题与版本的顺序。
  • 公开源码仓库不得新增包含详细研究过程、内部判断、市场材料或完整开发计划的 Research/、research/、Plan/、plan/ 目录或同类文档。
  • 公开源码仓库的 TODO.md、README、技术文档和代码注释只保留实现所需的简短结论、公开行为、兼容边界和验证状态；需要详细内容时引用私有仓库中的对应文档，不复制全文。
  • 新建或更新研究、计划类文档时，必须同时确认其保存在私有仓库，并在交付说明中给出实际路径。

iOS 仓库边界

  • iOS App 已由独立私有仓库维护；本仓库不得重新创建 Apps/RemoteMicIOS/、iOS 工程或 iOS 专属 CI。
  • 本仓库只维护 Mac 端附近连接、授权、按键执行和音频接收。
  • 修改共享手机协议时必须保持字段可选并兼容旧版 iOS，同时在独立 iOS 仓库完成对应验证；纯 iOS UI、TestFlight 和 iOS 设计素材不在本仓库处理。

Web 与服务器仓库边界

  • Web 前端和公网中继服务已分别由独立私有仓库维护；本仓库不得重新创建 Apps/MobileWeb/ 或 Web/服务端专属 CI。
  • 本仓库继续维护 Mac 端的 Web 会话客户端、协议解析、批准流程、按键执行、音频接收和发布配置，不得因源码拆分改变这些现有行为。
  • 修改 Web 协议时必须保持已发布 Mac 版本兼容，并在前端、服务端和本仓库分别完成对应测试；生产域名、服务器、证书和凭据仍不得进入 Git。