omdp: Instructions file for Codex

AGENTS.md — OMDP 仓库开发规范

本文档约束任何在 D:\WorkSpace\omdp 仓库内工作的 agent（含后续会话）。 仓库 = @omdp/* 系列 DSH 插件 monorepo（当前活跃：dsh-connector、 dsh-key-fallback、dsh-archived-sessions；历史归档在 archive/， 含 2026-10-18 起停用的视觉插件 dsh-vision-bridge）。

工作前提（先读再做）

• 动手改动任何 DSH 插件前，先研读 DSH 源码/官方文档/相关插件真实实现， 禁止凭印象或猜 API（维护/优化/编写插件铁律）。
• 删除任何文件前，逐条列出完整绝对路径核对；有价值先备份；删后立即验证。
• 本仓库是普通 JavaScript（无构建步骤），本地优先用 link: 安装调试。

规范 1：文档随插件同步更新

插件有任何更新（源码、配置、版本号、行为变化、发布动作）时，必须主动同步更新所有相关文档：

• 对应插件自己的 README.md（及双语 README.zh-CN.md）——功能、版本、Requirements；
• 根 README.md——插件列表/版本号/目录树有变化时；
• docs/ 下相关文档——plugin-compatibility.md（兼容性矩阵）、npm-publish.md（发布流程）等；
• 若改动产生了新的坑或经验，同时遵守规范 2 追加笔记。

判定标准：一次插件改动完成后，git 提交里应同时包含「代码/配置改动」与 「所有受影响文档更新」，不允许只改代码不带文档提交。

规范 2：教训经验主动沉淀为文档笔记

在维护、创建、修改插件过程中产生的教训、经验、坑、决策依据、可复用结论， 都要在工作完成后主动写入文档笔记，结构为三层：

notes/                        # 第一层：文档笔记
  └── <yyyy-MM-dd>/           # 第二层：时间（按日期排序）
      └── <category>/           # 第三层：按功能/主题分类
          └── <描述性名称>.md    # 一篇笔记一个主题

• 时间层：YYYY-MM-DD 格式（如 2026-08-28/），自然排序即时间线。
• 分类层（第三层），按主题归类，先有稳定分类再用新分类：
  • dsh-compat/ — DSH 版本适配/兼容性排查
  • plugin-dev/ — 插件开发/重构/架构
  • dsh-internals/ — DSH 源码研究（API 契约、事件载荷）
  • deploy/ — 部署、发布、npm
  • debug/ — 排障记录（根因→修复→验证）
  • tooling/ — 环境、工具链、git/npm/sandbox 坑
• 一篇笔记一个主题，文件名用简短描述（kebab 或直接中文皆可）； 内容至少含：背景/问题 → 结论或根因 → 可复用要点（含相关文件或命令）。
• 写完笔记在当次回复中提一句，随同一提交入库。

笔记索引

notes/README.md 维护目录结构与命名约定（见上）。笔记不需要全局索引—— 按「时间 → 分类」定位即可，必要时在 docs/ 里放跨笔记的汇总文档。

规范 3：版本声明严谨性（peerDependencies 用「三元组区间」放行）

插件声明对 DSH 生态包（@deepseek-ai/*）的 peerDependencies 时，用按 [major,minor,patch] 三元组划分的闭区间，上界必须带 -0：

• ✅ >=0.1.7-rc.1 <0.1.8-0 || >=0.2.0-rc.1 <0.2.1-0（每个已实测三元组一段，|| 串联）
• ✅ >=0.2.0-rc.1 <0.2.1-0（实测 rc.1 ⇒ 自动放行 rc.2 / rc.3 / 正式版 0.2.0）
• ❌ 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1（逐版本枚举：每发一个 rc 都要改声明 + 重发包）
• ❌ >=0.1.0-rc.6 <0.2.0、^0.1.0-rc.6（跨 minor 的开放范围，覆盖未测版本）

🔴 上界必须写 <下一 patch>-0，绝不能写 <下一 patch>：