Universe-Keyboard: Instructions file for Codex

AGENTS.md

本仓库的 AI 协作规则。所有 agent 在开始工作前必须先阅读本文件。

基本沟通规则

• 始终使用中文回复。
• 除非用户明确要求实施或修改，否则先讨论方案，不直接改文件。明确授权后，在该任务范围内持续推进；不因加载技能、角色切换或上下文压缩重复请求相同授权。
• 代码改动必须优先保证可读性。
• 可以适当增加注释，但注释应解释意图、边界或复杂原因，避免复述代码。
• 遇到不确定问题时，先核查事实并区分假设。已授权范围内的常规实现选择可自主决定；影响产品合同、权限、必需证据或不可逆动作的缺口才请求决定。
• 适当使用第一性原理分析：输入是什么、状态在哪里、副作用是什么、输出如何验证。

工作入口

新会话开始时先阅读：

1. AGENTS.md
2. docs/KNOWLEDGE_INDEX.md
3. docs/ACTIVE_WORK.md（当前 Active 工作项 ≤10；生命周期以 Assignment 为准）
4. 按 docs/READING_MAPS.md 中的任务类型加载对应文档
5. 涉及代码改动时再阅读 docs/PROJECT_CONTEXT.md
6. 运营卫生规则见 docs/kos/kos-2.1-operational-maturity.md（不替代 KOS 2.0 冻结原则）
7. KOS 2.2 目前为 advisory，Adopted pin v0.7.0：入口是 docs/kos/UPGRADE_STATUS.md 与 .kos/project.json。校验绿不是 Product / merge / Release。未授权 required。

CONTEXT_INDEX.md 保留为详细文档注册表，不再是新会话的第一导航入口。 需要确定长期团队所有权、跨线程协作或永久线程 bootstrap 时，阅读 docs/VIRTUAL_ENGINEERING_TEAM.md。 正式任务进入 Ready 或开始执行前，必须按 docs/ASSIGNMENT_POLICY.md 核对 Assignment；任何必需字段为 UNKNOWN 时停止并交回 Product Lead。边界明确的只读问题使用该 Policy 的例外。阶段依赖与当前授权解释见 docs/AI_WORKFLOW.md。 需要领域 agent 时，必须选择 docs/playbooks/ 下的对应操作手册，并遵守其停止、交接和证据规则。

调试原则

• 根因不清楚时，不要直接猜修。
• 优先增加精准日志、复现路径和观测点。
• 对输入法卡死、延迟、候选异常、RIME session 异常等问题，先区分：
  • UI 主线程问题
  • KeyboardCore 状态机问题
  • RIME session / bridge 问题
  • App Group / 文件系统 / 部署状态问题
• 日志必须放在能缩小问题范围的位置，避免无意义刷屏。
• 输入热路径中的日志和持久化不能同步阻塞按键处理。

修改边界

• 不做与任务无关的重构。
• 不随意改动 RIME 部署边界：主 App 可部署，Keyboard Extension 运行期只处理 session。
• 不用 @unchecked Sendable 或不安全隔离来绕过 Swift 6 并发问题。
• UI 改动必须遵守 docs/UI_STYLE_GUIDE.md。
• 修改 Packages/KeyboardCore 时优先补充或更新单元测试。
• 修改历史、决策或已知限制时，更新对应文档，不把流水账塞进 docs/PROJECT_CONTEXT.md 或 CLAUDE.md。

GitHub 发布与分支清理

• Codex 沙箱内的 GitHub CLI 认证失败不得单独解释为 token 过期。先按 docs/kos/codex-github-cli-auth-troubleshooting.md 做一次沙箱／主机对照；主机成功后停止重复登录，不猜测或复用旧代理配置。
• 发布按用户授权的具体动作推进：commit、push、PR、merge、Release 分别核对范围。仅要求本地提交不推送；推送使用边界清晰的功能分支。技能不能扩展外部动作权限。
• 合并 / 视为可合并之前，必须先在本地跑通与 CI 等价的质量门（见下「本地 CI 门禁」）。禁止在相关套件未绿时推送并请求合并到默认分支；若用户明确说「只推不合并 / 草稿 PR」，可推功能分支但必须在报告中写明本地未跑或未绿的步骤。
• “已推送功能分支”不等于“可以清理分支”。PR 未合并、检查失败或远端状态无法确认时，必须同时保留本地和远端功能分支。
• 只有在拉取最新远端状态后，确认该工作的提交已经可从 origin 的默认分支到达，才允许清理功能分支。
• 清理时先同步默认分支，再使用安全删除方式删除本地分支；确认远端默认分支仍包含对应提交后，才删除远端功能分支。禁止用强制删除掩盖未合并状态。
• 发布与清理过程必须报告提交、远端分支、PR、合并可达性检查和实际删除结果；任一步失败都停止清理并保留可恢复检查点。