dsh-enhanced-plugins AGENTS.md

AGENTS.md — DeepSeek Harness 插件项目通用规则

本文件适用于采用它的整个仓库，可复用于不同的 DeepSeek Harness（下称 DSH）外部插件项目。规则不得写入某个插件独有的协议、namespace、业务对象、字段或产品行为；项目专属事实应从当前仓库的 README、manifest、源码和测试中读取。

权威来源与开始工作前的检查

• 使用本规则的仓库是 DSH 插件项目，不是独立应用、DSH fork 或 DSH 内置 package。默认通过公开插件扩展点实现需求，不为接入插件而修改 DSH 本体。
• 本地 DSH 源码的固定位置是 D:\work\workspace\github\deepseek-harness。开始任何涉及 DSH API、构建、运行时或 UI 的工作前，先确认该目录存在；若不存在，停止相关工作并向用户询问，不得自行克隆、改用其他 checkout 或猜测接口。
• 先检查当前插件仓库的 package.json、锁文件、README、构建配置、patch、exports、源码目录和测试，确定它实际包含 Host、Client、Service、Tool、Provider、Consumer 或 bundle 中的哪些部分。不得假设所有插件都有相同目录结构或同时包含 Host/Web 两半。
• 官方技术文档入口如下。这些 URL 是章节入口而非单页；根据任务沿侧边栏继续阅读相关子页，不能只读取入口页：
  • https://deepseek-harness.github.io/deepseek-harness/guide/quickstart
  • https://deepseek-harness.github.io/deepseek-harness/develop/basic/
  • https://deepseek-harness.github.io/deepseek-harness/reference/
• 插件生命周期、服务、事件、配置、发布或 UI 任务必须继续阅读对应的 Develop、Cordis tutorial、Cordis API、subsystem 和 cookbook 子页。设置界面任务还必须阅读 reference/cookbook/adding-a-settings-card、reference/subsystems/client-modules 与 reference/subsystems/settings。
• 在线文档表达公开设计和最新约定，本地 checkout 表达当前实际 ABI、slot 结构和视觉实现。两者不一致时，记录本地 commit，核对目标版本的类型与源码，采用能在该 checkout 上验证通过的接口并说明差异；不得静默拼接两个版本的 API。
• 将 sibling checkout 视为只读参考和联调目标。除非用户明确要求，不得在 D:\work\workspace\github\deepseek-harness 中提交、格式化、生成或修改文件。

插件架构与职责边界

• 遵循 DSH“行为由插件组成”的架构。新行为应进入已有公开 Service、event、registry、slot、settings 或 bundle 扩展点；不要修改 agent loop、Web shell 或其他核心包来绕过缺失的插件接入。
• 先识别当前插件在 capability seam 中的角色：Service Definition、Provider、Consumer，或只负责组合它们的 bundle。新增能力时必须考虑当前所需角色及其真实调用方，不把 provider 私有行为塞进公共 service，也不把某个 UI/transport 的需要写进通用 service 接口。
• 保持 Host、Client、模型可见行为、持久化和 transport 的职责分离。跨插件协作通过 Cordis service、typed event、registry 或 typed slot；不要导入另一个插件的私有实现来共享状态。
• 除非需求明确改变公开结构，保留当前仓库已经声明的 package 边界、入口、subpath exports 和 patch 组合方式。不要为了套用别的插件示例而重排现有架构。
• 所有新增公开行为都要有明确所有者。配置由注册 namespace 的插件所有，UI 只编辑；持久状态由拥有它的 subsystem 所有；transport 只负责传递，不成为业务真源。

Cordis 插件与生命周期

• 函数插件把适用的 name、inject、Config、apply 元数据作为命名导出，不要混入 default export；提供具名服务的插件才使用默认导出的 Service 子类。以目标 checkout 当前 package 约定为准。
• 必需服务写入 inject，让 fiber 等待依赖并在依赖消失时自动卸载；可选服务在使用点通过 ctx.get(name) 查询。不要通过手工启动顺序代替依赖声明。
• 所有注册和资源必须属于 fiber 生命周期。优先使用本身可撤销的 ctx.on()、registry register() 和 ctx.plugin()；Cordis 不管理的连接、定时器、watcher、订阅或进程必须放入 ctx.effect() 并返回 disposer。
• ctx.plugin() 创建的 child fiber 随父级卸载。需要提前替换或终止时等待 fiber.dispose() 完成；不能泄漏注册、子进程、网络连接、监听器、重试或后台任务。
• 异步 disposer 之间需要顺序时，把相关步骤放进同一个 disposer 并显式串行等待；不要依赖多个 effect 的完成顺序。实现必须能经受配置更新、依赖消失、显式 dispose 和 HMR。
• 新 registry contribution 必须验证 dispose 后确实移除。配置热替换不得留下旧实例状态；用稳定 entry id 保持 Loader/HMR 只重载发生变化的部分。
• waterfall listener 除非明确拥有短路决策权，否则必须调用 next()；事件模式是公开约定，使用与声明一致的 emit、waterfall、parallel 或 serial 分发方式。
• 需要跨插件公开能力时使用 Service；仅由单个实现内部使用的逻辑保持私有。函数、service、事件和声明合并均使用目标 package 的公开入口，不从 src/ 或未导出的内部路径导入。