AGENTS.md git:20260923.d90f6ceA

Immutable. This exact content never changes and is served at /api/v1/blob/02ff92c820a6a7d3.

# 仓库维护约束

## 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 自身及其配套机制的修改，明确要解决的问题及必须保持的行为，按实际影响选择已有证据。日常维护和发布不默认要求全量题本、A/B、弱模型或多模型裁判；结构调整和文字压缩本身不触发模型评测。只有具体未决问题会改变实现、保留或退役决定时才做最小实验；超时不自动产生重跑任务。
- 保留保护用户数据、权限、安装恢复、发布契约和已发生缺陷的程序回归；删除只锁定提示措辞、内部排列或固定 token 估算值的断言。文字整理用全文审阅和完整性检查，执行逻辑改动验证受影响的真实行为，不为测试数量或覆盖率补设施。效果或成本改善的公开声明仍须有可比实测证据，未测的不宣称改善；旧结果不自动证明新版本质量。
- 评测维护、题本设计、裁判与报告整理仍按上述要求治理；真正受测的 runner 则严格服从冻结的评测臂，不继承本节。`on` 只加载该臂声明的冻结 skill 与项目材料；`off` 必须在干净隔离环境运行，不读取或注入 odai、`.odai/local.md`、odai 路由或 Hooks、要求使用 odai 的仓库指令、其他臂输出、既往 runner 转录或其派生状态。

## 官方 skills 单一事实源

- `skills/odai/`、`skills/odai-orchestration/` 与 `skills/ribao/` 是各自唯一可编辑的 source。odai 提供独立治理；odai-orchestration 是单向依赖治理的可选编排技能；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` 负责工具、资料与技能的选择，`references/memory.md` 负责长期信息、项目叠加层与项目规则和技能的固化；reference 只写入口之外的增量，不复述 `SKILL.md`。编排技能的 `references/orchestration.md` 负责职责选择、调度和交接；角色合同只引用对应 owner，不复制另一层的清单或宿主机制。
- 有来源的操作规则登记在 `docs/rule-ledger.md`。改写、压缩或重组治理正文时逐条核对账本规则仍在所列 owner 中成立；删改账本规则须在 CHANGELOG 写明问题与理由。
- 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 发布事实。

## DSH 集成修改边界

- `odai-dsh-plugin` 与 `odai-dsh-agent` 的问题必须在本仓库内解决；修复实现、兼容层、配置、补丁、测试和文档只能落到本项目受版本控制的文件中。
- `skills/odai/` 只承载跨宿主治理，`skills/odai-orchestration/` 承载通用编排与角色合同；DSH 的 hook、工具名、same-turn / child 调度、路由状态、证据事件、provider / model 字段与 token 优先级必须落在 `dsh/runtime/`，不得为方便复用写入 canonical skill、通用角色正文或 `.odai/local.md`。
- DSH 可在运行时组合 canonical 通用合同与 `dsh/runtime/` 私有补充合同。语义是否上移 canonical 由责任归属与证据决定，不设固定宿主数量门槛：只有该语义跨宿主成立、不含 DSH 机制，证据足以支持其通用净收益，且兼容影响与迁移已明确验证时才上移；单一宿主暴露问题既不自动证明通用，也不自动阻止通用治理修正。需要新增 required file 或改变读取契约时必须显式升级 skill version / runtime contract，不得顺带修改。
- `AGENTS.md` 只记录上述稳定落位规则；具体触发条件、事件字段、预算值和实现流程以 `dsh/runtime` 源码及同目录测试为事实源，避免文档副本漂移。
- `odai-dsh-agent` 与 `odai-dsh-plugin` 作为同一发布单元维护；从 `0.0.10` 起两个 `package.json` 的版本号必须完全一致，同一功能发布同时升版。测试与 prepack 必须运行仓库版本一致性检查，禁止单包漂移或用已发布旧版本承载新改动。
- DeepSeek Harness 的源码 checkout、全局或本地安装包、`node_modules/@deepseek-ai/dsh` 及其核心文件一律只读，只能用于定位行为、核对契约和运行兼容性验证；不得直接修改、打补丁或用本机改造后的 DSH 冒充本项目修复。
- 必须处理 `$DSH_HOME` 中既有用户数据时，只能通过本项目内受版本控制、可审计并带备份与验证的迁移入口执行；迁移须遵守用户授权和停机要求，不得手工篡改 DSH 会话、profile 或核心状态来绕过问题。