omdp AGENTS.md

AGENTS.md — OMDP 仓库开发规范

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

工作前提（先读再做）

• 动手改动任何 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/ 里放跨笔记的汇总文档。

提交约定

• 一次完成的工作（含文档 + 笔记）建议一次提交；
• 提交信息写明：做了什么 + 涉及哪些文档/笔记。