git:20260922.fd5280b to git:20260922.f8b3ea6

# AGENTS.md - OMK 项目约定

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

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

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

## 开工与交付

- 涉及 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`。

## 自主 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 是 Node 侧的确定性测量内核：不反向依赖 CLI、文件系统、网络、环境变量、具体执行器或 Studio。「宿主无关」指的是这些外部依赖，不含 Node 运行时本身——core 直接用 `node:crypto` 做规范化摘要，不注入化、不声明可在浏览器或边缘运行时执行。Core 只表达纯契约与确定性变换，副作用放在 eval-workflows 或对应 adapter。

- 保留来源、时间、关联身份与原始证据；派生视图不覆盖原始证据，观测信号不冒充因果结论。

- 测试使用显式临时根和环境隔离，覆盖失败／中断后的 cleanup 路径；生产写入只落到公开存储契约允许的位置，不擅自写用户目录或全局状态。

- 新建或可安全改名的判别字段使用 eventKind、runtimeKind 等限定名；裸 kind 默认保留给 Artifact.kind。已发布、落盘或对外暴露的 public schema 既有 kind 不顺手改名；必要改名单独版本化并显式声明不兼容，不为旧版本保留兼容 reader——Resolver 只认当前版本，旧文档读不回是既定策略。细节见 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。

- 短分支名前缀取该分支主要改动的 Conventional Commits type（`feat/`、`fix/`、`docs/`、`refactor/`、`test/`、`perf/`、`chore/`、`ci/`），与提交信息的 `type(scope):` 保持一致，不与工具、模型或人员绑定；一个分支承载多类改动时不勉强对齐。

- 提交格式为 type(scope): 中文 subject，scope 使用稳定模块名，本文件使用 agents-md。

- 用户可见文案中文优先，中文使用全角标点；代码、路径、命令、URL、frontmatter、数学区间、技术标识符及英文技术括注保留对应语法。Conventional Commits 的 type(scope): 前缀保持半角。

- LLM judge 统一称为“评委”，不称“判官”。PR 审查评论语言跟随用户操作系统设置语言。

- 创建 PR 默认使用非草稿状态；仅在用户明确要求草稿时使用 Draft。未完成的验证、已知问题和合并阻塞在 PR 描述中如实记录，仍须满足门禁与完成定义后才能合并。

- PR 边界在开工划分工作时就确定，不等自主 CR 阶段才收拢；口径的唯一完整表述见 CODE_REVIEW.md「实现中保持可审查」。

- 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/（英文 `docs/`、中文 `docs/zh/`，逐节对照由 CI 门禁判）。

- Git 与发版：CONTRIBUTING.md 是指针，正文在文档站 `docs/guides/contributing.md` 与 `docs/zh/guides/contributing.md`。