AGENTS.md · diff
git:20260913.7b88b62 to git:20260914.8826e8a
11 added, 2 removed. Audit A to A.
# AGENTS.md - OMK 项目约定
OMK（Observe. Measure. Know.）通过固定模型、改变知识载体，观测和测量 prompt、RAG、skill、agent、workflow 的版本差异。所有改动优先保护测量可比性、证据完整性和用户数据。
本文件是工具中立的项目入场清单。Claude Code 通过 CLAUDE.md import；不为不同工具复制维护第二份项目规则。
## 开工与交付
- 涉及 commit、PR、分支或发版时，读取 CONTRIBUTING.md 的相关流程；同一任务已读且未变化时复用。
- 修改子目录前，检查从仓库根到目标文件路径上的 AGENTS.md，最近的文件补充或覆盖上层项目约定；普通局部任务不遍历全仓规则。
- - 开工先明确需求、非目标、受影响边界和风险。用户确认方向后，在已授权的交付链内连续推进，不在实现、验证、自主 CR 等常规步骤间反复询问下一步。
+ - 开工简述需求、非目标、受影响边界和风险，低风险改动一两句即可；当前任务已明确方向即按已有授权连续推进，不在实现、验证、自主 CR 等常规步骤间反复询问下一步。
- 用户已授权 OMK 改造的默认交付链：自主完成实现、验证、自主 CR、提交、推送、创建 PR，并在相关门禁和远端 CI 通过、审查问题按完成定义处理后合并到 main，无需逐次确认提交、PR 或合并。此授权适用于当前及后续改造任务；用户对具体任务的只读、仅本地、不提交或不合并等明确限制优先。
- 发版仍需单独授权，不将合并等同于发布授权。默认交付授权不扩大需求范围，也不绕过公共契约／存量数据变更的确认要求、平台审批、仓库保护或其他高影响操作的授权边界。
- 默认直接替换旧实现，不为没有明确需求的旧入口、旧字段或旧行为保留兼容层、别名和双轨分支。涉及已发布的公共契约或存量数据时，先说明影响与替换／迁移方案，向用户确认后执行，不自行决定兼容，也不直接做破坏性替换；当前任务已有明确决定时不重复确认。必要的破坏性变更仍须遵守下述版本化与迁移要求。
- 长任务及时更新对应 Issue／PR 的已有执行清单，状态以实际完成情况为准。
- - 开发反馈优先跑受影响验证；首次 push 前默认跑一次 yarn ci，除非用户明确要求更窄验证，或改动仅限不影响生成产物、链接、打包与行为的手写文档／规则。首次 push 后事实未变化时，不为交付机械重跑本地门禁；存在远端 CI 时，以其结果补充确认。事实变化时，后续修复成批完成，并按影响范围重跑精准验证或完整门禁，不把远端 CI 当作增量反馈环。
- 测试维护同时做加法和减法：新增或迁移测试时，审视受影响的既有用例，删除失效或仅绑定已替换实现细节的断言，合并重复覆盖，优先复用、改写现有测试；不以用例数量增长代表质量提升，也不为减少数量牺牲关键行为与失败路径的覆盖。
- clean-room 验收只在发布、打包／安装契约变化、真实用户入口变化或风险审查明确要求时执行；触发条件、被测边界与证据未变化时不重复执行。
- 人工启动 Studio 供用户查看时，优先使用用户指定的固定端口，否则使用 CLI 默认固定端口；不主动传 `--port 0`。端口占用时先识别已有服务，确认属于本任务后再复用或重启，不擅自改用随机端口。随机端口仅用于隔离自动化测试或用户明确要求的场景；展示地址仍使用 `server.start()` 返回值。
+
+ ## 开发反馈与验证
+
+ 本节是验证触发与结果复用的唯一规则来源；具体命令与构建依赖见 `CONTRIBUTING.md`，审查方法见 `CODE_REVIEW.md`。
+
+ - 从目标文件和直接调用边界检索，按证据扩大范围；独立只读操作批量执行。复用未变化的规则和证据，不因进入下一阶段重读或全仓扫描。
+ - 每轮修改优先 `yarn test <测试文件...>`，保留工作树污染检查；阶段收尾需要组合静态检查时使用 `yarn ci:quick <测试文件...>`。不直接用 Vitest 绕过隔离入口，也不要求每轮都跑快速门禁。源码测试可跳过构建；依赖 dist／真实 CLI／Next 生产资源的测试先更新对应产物，不能用旧产物证明新源码正确。
+ - 首次 push 前在最终改动集上默认跑一次 `yarn ci`；例外仅为用户明确要求更窄验证，或不影响生成产物、链接、打包与行为的手写文档／规则。`ci:quick` 不替代完整门禁。
+ - 首次 push 后事实未变化时复用本地结果，以远端 CI 补充确认；后续修复成批完成，按影响范围重跑精准验证或完整门禁，不把远端 CI 当增量反馈环。记录命令、被测改动及未覆盖边界；代码、依赖、配置或环境变化使旧证据失效时，仅补足失效范围。
+ - 等待原有进程／CI 句柄，不因观察超时重新启动。需求满足、必要验证通过、审查问题处理完毕即交付；无新证据不重复构建、完整 CR 或 clean-room 验收。
## 自主 CR 与完成定义
- 改变行为、契约、打包、文档承诺或仓库规则的改动，在首次 push／交付前自主完成一次 CR；纯机械改动快速复核，深度与风险匹配。
- 首次自主 CR 前必须完整阅读 [`CODE_REVIEW.md`](./CODE_REVIEW.md)；同一任务规则未变化时复用，不重复加载。以审查者视角只读检查最终变更、直接调用边界、契约和验证证据；发现跨模块影响时沿证据扩大范围。可使用独立 reviewer，否则做 fresh-pass 自审。
- P0～P2 在交付前解决，P3 解决或登记 follow-up。修复后复查受影响面并重跑受影响验证；只有架构／公开行为实质变化、CI 新问题、重要 rebase 冲突或外部审查提出新高风险方向时，才重新做完整 CR。
- Finding 的证据、优先级和格式遵守 CODE_REVIEW.md。无 finding 时明确说明，不制造猜测性问题；门禁、真实用户路径和未验证范围如实报告，不以 CI 绿色代替需求完成。
- 用户要求审查具体 PR 时，将结论直接发布到对应 PR；用户明确要求仅本地审查时不发布，未指定或无法确定对应 PR 时不猜测发布对象。
### CR 运行产物隔离
- artifacts/cr/ 和 knowledge/cr/ 不是源码资产，不得在仓库内创建或保留，也不用 .gitignore 隐藏。纯只读审查不创建过程文件；只有实际运行会写盘的 CR 工具时，才用唯一仓库外临时目录保存全部运行产物，并显式配置输出路径，不得执行回写仓库的结果同步。
- CR 前后检查工作树状态，确保审查工具未产生额外污染，不清理或覆盖用户原有修改。Issue／PR／CI 是持久审查记录；只有用户明确要求时才将报告作为项目资产提交。
## Code Review Rules
- 不静默改变评分口径、统计语义、prompt 字节、Schema identity 或持久化契约。必要变更显式版本化，在 PR 标题／描述标记对应 BREAKING-*、迁移及测量影响。
- eval-core 保持宿主无关和确定性，不反向依赖 CLI、文件系统、网络、环境变量、具体执行器或 Studio。Core 只表达纯契约与确定性变换，副作用放在 eval-workflows 或对应 adapter。
- 保留来源、时间、关联身份与原始证据；派生视图不覆盖原始证据，观测信号不冒充因果结论。
- 测试使用显式临时根和环境隔离，覆盖失败／中断后的 cleanup 路径；生产写入只落到公开存储契约允许的位置，不擅自写用户目录或全局状态。
- 新建或可安全改名的判别字段使用 eventKind、runtimeKind 等限定名；裸 kind 默认保留给 Artifact.kind。已发布、落盘或对外暴露的 public schema 既有 kind 不顺手改名；必要改名单独迁移并保持旧文件可读。细节见 docs/specs/terminology-spec.md §5.4。
- 用户可见服务 URL 使用 server.start() 返回的实际地址，不硬编码端口。
- .agents/skills/omk/ 是官方 Skill 单一来源，.claude/skills/omk 保持软链，不复制第二份；本文件不重复 Skill 用户教程。
## Git 与写作
- main 是唯一长期分支；从 main 创建短分支，通过 PR 合并，不直接提交 main，也不恢复 develop 流程。发版通过短分支 PR 回 main，再由 tag 触发；具体流程见 CONTRIBUTING.md。
- 分支默认使用 codex/ 前缀。提交格式为 type(scope): 中文 subject，scope 使用稳定模块名，本文件使用 agents-md。
- 用户可见文案中文优先，中文使用全角标点；代码、路径、命令、URL、frontmatter、数学区间、技术标识符及英文技术括注保留对应语法。Conventional Commits 的 type(scope): 前缀保持半角。
- LLM judge 统一称为“评委”，不称“判官”。PR 审查评论语言跟随用户操作系统设置语言。
- PR 说明用户影响、迁移及测量限制，链接相关 Issue／前置 PR；不堆叠行号、测试清单或 diff 已体现的嵌套实现细节。
- 对话回复中引用远端对象（PR、Issue、commit、Actions run／job、文档、本地服务地址）时，在同一句话里给出可点击 URL；URL 取自 CLI 输出的现成字段，不自行拼造，取不到就只写名称。
## 参考入口
- 用户文档：README.md、README.zh.md。
- Skill：.agents/skills/omk/SKILL.md。
- 审查：CODE_REVIEW.md。
- 设计规范：docs/。
- Git 与发版：CONTRIBUTING.md。