odai AGENTS.md

仓库维护约束

odai 必用

• 本仓库中的每次用户请求都必须使用 canonical skills/odai/SKILL.md 治理。若宿主明确声明当前 odai-dsh-agent 或 odai-dsh-plugin 已把完整 canonical governance 注入系统提示，并给出 skill version、runtime contract 与 bundle digest，则该注入本身视为已完整加载；声明有效且本会话未改动 canonical bundle 期间，不得再调用 skill 或 read 重复载入同一正文。仅当注入声明缺失或不可信、任务直接审查或修改 Odai、或 manifest 声明的 canonical 文件在注入后发生变化时，才须在行动前完整读取当前 SKILL.md，并以新内容继续治理。其他宿主若当前任务尚未完整读取其当下版本，任何调查、判断、修改或测试前先完整读取。
• 按 odai 的真实缺口决定是否读取支撑资料；使用 odai 不等于自动增加计划、路由、角色、文件、测试或流程，简单任务仍直接完成。
• 对 odai 自身及其配套机制的修改同样受 odai 治理：先判断是否必要、是否比现状更成事、是否有可验证净增益，再决定保留、修改或退役，不因已有实现、历史方案、题本得分或局部可实现性继续堆叠。
• 以减少 token、延迟或成本为目的的优化，必须先用行为契约、反例与测试证明既有能力和安全边界不退化，再评估节省是否成立；不能验证保持项、只测预算下降、依赖模型自报或以删除能力换取指标时，不得合入或发布。
• 评测维护、题本设计、裁判与报告整理仍按上述要求治理；真正受测的 runner 则严格服从冻结的评测臂，不继承本节。on 只加载该臂声明的冻结 skill 与项目材料；off 必须在干净隔离环境运行，不读取或注入 odai、.odai/local.md、odai 路由或 Hooks、要求使用 odai 的仓库指令、其他臂输出、既往 runner 转录或其派生状态。

官方 skills 单一事实源

• skills/odai/ 与 skills/ribao/ 是各自唯一可编辑的 canonical source；odai 是统一入口与最终交付 owner，ribao 是可独立加载的专业汇报能力。
• cli/skills/ 不在仓库中常驻；它只由 npm prepack 临时生成，并在 postpack 清理。
• 即使用户或 IDE 指向打包期间临时出现的 cli/skills/，也要把对应修改落到仓库根 skills/<name>/。
• source 修改完成后，运行 node scripts/validate-odai-skill.mjs 验证 canonical skills。
• canonical references 按单一所有权维护：references/planning.md 只负责正式计划、可执行合同与跨轮续作，references/craft.md 只负责已决定结果的制作工艺，references/leverage.md 只负责能力与责任选择、调度和交接；角色合同只引用对应 owner，不复制另一层的清单或宿主机制。
• odai-cli 未冻结时，发布相关修改还需运行 npm --prefix cli run pack:dry-run，确认产物与当前声明的打包范围一致，且命令结束后没有遗留 cli/skills/；冻结期间遵循下节边界。

odai-cli 冻结边界

• cli/、plans/odai-cli-plan.md 与 plans/odai-cli-runtime-canary.md 当前冻结，不属于 active canonical / DSH 维护与验收范围。除非用户明确重新开放，不修改、测试、打包、升版或发布 odai-cli，也不为兼容它改变 canonical 或 DSH 路线。
• 冻结期间，canonical / DSH 变更不运行 CLI tests 或 npm --prefix cli run pack:dry-run；只记录可能影响未来恢复的已知差异。cli/skills/ 仍不得作为可编辑 source 或遗留在仓库中。

版本发布约束

• 从本约束生效后的首个候选版本起，本仓库自有的任何新版本标识都不得包含数字字符 4；npm package version、skill version 与 runtime contract version 均受约束，版本序列遇到含 4 的候选值时必须直接跳过。已发布历史版本及其兼容记录必须按事实保留，不因本约束改写；上游依赖版本不属于本仓库自有版本，不受此规则限制。
• 禁止只靠人工记忆执行本约束。所有发布入口与版本事实源必须调用仓库的统一版本策略校验；新增版本载体时必须同时纳入该校验，命中禁用字符即 fail-closed。
• 同一 npm 候选从未发生过 registry publish，且未废弃或经用户明确拆分时，后续改动继续归入该候选；不得仅因新一轮任务、canonical / runtime contract 变化或新增 changelog 内容另起包版本，也不得把当前候选写成历史。版本一旦曾发布，即使后来 unpublish 或 deprecate，该标识也视为已消耗，不得复用。改版本前先核对 package metadata、当前唯一 Unreleased owner 与真实 registry 发布事实。