oh-my-knowledge: Instructions file for Codex

AGENTS.md - OMK 项目约定

本文件与各目录的领域 AGENTS.md 只维护中文：它们是被 Agent 按路径加载的指令来源，不存在英文版，也不做双语副本（GitHub 与各工具都只认 AGENTS.md 这一个文件名）。人类贡献者的流程入口是 CONTRIBUTING.md，其正文在文档站，中英两版都有。

OMK（Observe. Measure. Know.）通过固定模型、改变知识载体，观测和测量 prompt、RAG、skill、agent、workflow 的版本差异。所有改动优先保护测量可比性、证据完整性和用户数据。

本文件是工具中立的项目入场清单。Claude Code 通过 CLAUDE.md import；不为不同工具复制维护第二份项目规则。

做事原则

• 实际价值优先。 围绕真实使用者和具体任务，以实际成果和收益决定优先级；不以功能数量、工程进度或验证通过替代价值判断。
• 抓大放小，完成比完美重要。 先明确完成条件、投入上限和停止条件，优先解决关键阻断，复用有效证据；核心效果未成立时及时简化、收缩或停止，不持续追加机制。必要的质量门禁按下文执行。
• 先交付可评判的成果。 Agent 先做好基本可用性检查，提供具体结果再请用户判断价值；不把明显缺陷的排查或理解内部概念的负担交给用户。工程验收、Agent 自测与真人反馈分别表达。

开工与交付

• 涉及 commit、PR、分支或发版时，读取 CONTRIBUTING.md 的相关流程；同一任务已读且未变化时复用。
• 修改子目录前，检查从仓库根到目标文件路径上的 AGENTS.md，最近的文件补充或覆盖上层项目约定；普通局部任务不遍历全仓规则。
• 开工简述需求、非目标、受影响边界和风险，低风险改动一两句即可；当前任务已明确方向即按已有授权连续推进，不在实现、验证、自主 CR 等常规步骤间反复询问下一步。
• 用户已授权 OMK 改造的默认交付链：自主完成实现、验证、自主 CR、提交、推送、创建 PR，并在相关门禁和远端 CI 通过、审查问题按完成定义处理后合并到 main，无需逐次确认提交、PR 或合并。此授权适用于当前及后续改造任务；用户对具体任务的只读、仅本地、不提交或不合并等明确限制优先。
• 发版仍需单独授权，不将合并等同于发布授权。默认交付授权不扩大需求范围，也不绕过公共契约／存量数据变更的确认要求、平台审批、仓库保护或其他高影响操作的授权边界。
• 默认直接替换旧实现，不为没有明确需求的旧入口、旧字段或旧行为保留兼容层、别名和双轨分支。涉及已发布的公共契约或存量数据时，先说明影响与替换／迁移方案，向用户确认后执行，不自行决定兼容，也不直接做破坏性替换；当前任务已有明确决定时不重复确认。必要的破坏性变更仍须遵守下述版本化与迁移要求。
• 长任务及时更新对应 Issue／PR 的已有执行清单，状态以实际完成情况为准。
• 测试维护同时做加法和减法：新增或迁移测试时，审视受影响的既有用例，删除失效或仅绑定已替换实现细节的断言，合并重复覆盖，优先复用、改写现有测试；不以用例数量增长代表质量提升，也不为减少数量牺牲关键行为与失败路径的覆盖。
• clean-room 验收只在发布、打包／安装契约变化、真实用户入口变化或风险审查明确要求时执行；触发条件、被测边界与证据未变化时不重复执行。
• 人工启动 Studio 供用户查看时，优先使用用户指定的固定端口，否则使用 CLI 默认固定端口；不主动传 --port 0。端口占用时先识别已有服务，确认属于本任务后再复用或重启，不擅自改用随机端口。随机端口仅用于隔离自动化测试或用户明确要求的场景；展示地址仍使用 server.start() 返回值。

开发反馈与验证

本节是验证触发与结果复用的唯一规则来源；具体命令与构建依赖见 CONTRIBUTING.md，审查方法见 CODE_REVIEW.md。

• 从目标文件和直接调用边界检索，按证据扩大范围；独立只读操作批量执行。复用未变化的规则和证据，不因进入下一阶段重读或全仓扫描。
• 每轮修改优先 yarn test <测试文件...>，保留工作树污染检查；阶段收尾需要组合静态检查时使用 yarn ci:quick <测试文件...>。不直接用 Vitest 绕过隔离入口，也不要求每轮都跑快速门禁。源码测试可跳过构建；依赖 dist／真实 CLI／Next 生产资源的测试先更新对应产物，不能用旧产物证明新源码正确。
• 本地验证按风险分层：普通局部修改用 ci:quick 精准验证；跨模块、依赖、构建／打包、CI 门禁变化必须本地完整 yarn ci；测试依赖编译或生产资源时先更新对应构建产物再测试。首次 push 前在最终改动集上跑与该档位相称的那一层即为满足，不再无条件追加完整 yarn ci；风险档位判不清时按完整门禁。用户明确要求更窄验证时按更窄执行并记录未覆盖边界。ci:quick 不替代完整门禁。
• 首次 push 后事实未变化时复用本地结果，以远端 CI 补充确认；后续修复成批完成，按影响范围重跑精准验证或完整门禁，不把远端 CI 当增量反馈环。记录命令、被测改动及未覆盖边界；代码、依赖、配置或环境变化使旧证据失效时，仅补足失效范围。
• 等待原有进程／CI 句柄，不因观察超时重新启动。需求满足、必要验证通过、审查问题处理完毕即交付；无新证据不重复构建、完整 CR 或 clean-room 验收。
• 同一台机器上有需要互不干扰的并发工作时（例如另一份工作正持有未提交改动），该任务使用一份仓库外隔离检出，并默认复用它跑后续验证，不按阶段另开；确需第二份时说明用途，例如与改动前基线或不同依赖版本对照。销毁只针对本任务创建、无未保存改动、无运行中进程且用户无需继续查看的临时检出，销毁后同步清理其登记。
• 每份检出独立维护与自身产物绑定的可写构建状态（增量构建、类型检查与 lint 缓存）：共用会让缺产物的检出以退出码 0 假通过，这类构建结果不能当门禁证据。只读的软件包下载缓存不在此列，它位于各检出之外、保持共享即可；按条目软链依赖内容仅在版本与安装配置一致、且共享目标不会被并发改动时可用，否则由该检出自行安装，机制与实测见 CONTRIBUTING.md。