plugin-write

编写 DeepSeek Harness 插件

创建一个插件包。首先判断仓库模式和插件形式，然后阅读相应的参考文件，最后使用覆盖此次变更所需的最少检查来验证发布入口。

首先选择仓库模式

目标	适用规则
官方 deepseek-harness 单体仓库中的包	遵循下方有关仓库内包、tsconfig、文档和根级检查的规则。
可在外部安装的 DSH 插件	保留该仓库的包布局和脚本。只能使用目标 DSH 精确版本发布的包和导出项。不要复制 private、工作区版本、根 tsconfig 注册规则或仅适用于单体仓库的 README 检查。
要适配新 DSH 宿主的现有插件	阅读 references/version-adaptation.md，构建完整的版本范围，并运行七类触点预检。如果变更属于 breaking，且用户尚未授权实施，则提交迁移计划并等待确认。获得授权后，先完成版本适配，再使用此 Skill 的形式参考。形式示例绝不能覆盖目标源码、类型声明或发行说明。

从目标精确版本的清单中确定 Cordis、Schemastery 和 DSH 的包名及版本范围。当前示例使用带作用域的 @deepseek-ai/* 标识符。较旧的目标可能不同，必须遵循其自身已发布的契约。

对于每个新建的外部插件，在选择公共标识符之前，先阅读 references/naming-conventions.md。在插件仓库根目录创建 dsh-plugin.naming.json，并在最终包验证前运行随附的只读验证器。将兼容性错误视为目标契约失败；将前缀警告视为社区建议。只有在插件采用抗冲突配置时才使用 --strict。这不是官方 Harness 清单，也不是全局名称预留。对于现有外部插件，应报告命名偏差，但除非用户明确授权进行不兼容重命名，否则保留已发布的名称。官方单体仓库中的包应遵循目标检出版本，而不是此外部命名配置。

离线声明检查通过后，阅读 references/registry-check.md，并在公共网络可用时运行单独的中央查询。提供确切的目标 Harness 版本，并保留报告中的索引 SHA-256 和源 URL 作为证据。完整的无匹配结果只能视为“未发现经审核的匹配项”；超时、数据格式错误、不支持的契约、输入过大或网络故障均应视为“未知／未检查”。绝不能让在线查询修改本地清单、自动重命名已发布的接口，或将自动发现的候选项变成预留项。只有在明确选择中央注册时，才准备完整的 v2 条目，并在将其复制到 registry/entries 前运行中央仓库的 check 和 verify-source 命令。验证不代表已获准提交 PR；只有源代码有据可查的条目经过审核并合并到中央注册表后，才构成正式预留。

然后确定插件类型

所需能力	类型	参考文档
供模型调用的工具，用于读取文件、运行命令或搜索 Web	工具插件	references/tool-plugin.md
新的模型提供方	LLM 适配器插件	references/llm-adapter-plugin.md
为权限、策略、指标或遥测拦截请求、工具或轮次	Hook 插件	references/hook-plugin.md
通过 ctx 供其他插件使用的能力	服务插件	references/service-plugin.md
通过 cordis.yml 提供的用户可配置行为	配置插件	references/config-plugin.md

插件可以自由组合不同类型，例如可配置的工具插件，或同时注册工具的服务。每种类型仍须满足自身的契约。如果某项需求与上述五种类型均不匹配，请将其映射到现有扩展点，并编写一个在该扩展点注册的插件。切勿直接修改 Agent 循环。

目标	机制
添加供模型调用的能力	在 ctx.tools 上注册
添加模型提供方	在 ctx.llm 上注册适配器
为某个会话提供不同的能力集	在 Agent 预设中组装
添加 Shell 执行功能	实现并注册 ctx.bash 后端
添加持久终端执行功能	注册 ctx.pty 后端并加载 dsh-tool-pty
添加人工命令	在 ctx.commands 上注册
添加后台任务	在 ctx.tasks 上注册
添加文件系统访问或策略	实现 ctx.fs 提供方，或监听 fs/* 策略事件
限制启动的进程	使用 ctx.sandbox 后端
拦截请求、工具或轮次	使用 agent/* 或 tools/* 事件；agent/turn-stopping 是轮次停止事件
添加模型可见的上下文	调用 agent.inject()
添加 UI 或编辑器集成	驱动 ctx.agents，并从 session/event 渲染
添加 Web 客户端对话节点	注册 ConversationNodeDefinition 和带键的渲染器
添加持久会话状态	扩展 SessionEventMap，然后从日志渲染并重放
分叉实时会话	调用 ctx.sessions.fork(source, boundary?, childSessionId?)
将注册项限定在某个 Agent 的作用域内	使用该 Agent 的 agent.ctx

软件包检查清单

1. 创建仓库内软件包 — 仅在官方单仓库中创建 packages/<group>/<pkg>/，并包含 package.json、tsconfig.json、src/index.ts 和 README.md。从目标检出版本复制 packages/core/tools/package.json，然后调整其名称、描述和依赖项。保留目标版本不变量：private: true；根软件包的 version；type: module；main: "lib/index.js"；types: "lib/types/index.d.ts"；exports["."] 中的 types 和 default 均指向 lib；peer 依赖和开发依赖中的 Cordis 范围与目标版本一致；每项 DSH peer 依赖均在开发依赖中镜像声明；在 dependencies 中声明目标 Schemastery 软件包；以及目标 files 布局和软件包专属运行时产物。CLI 应用软件包必须包含构建后的 bin。不要发布未声明的源文件或过时产物。遵循目标检出版本的相对导入约定。优先选择角色匹配的现有分组。新分组仅作为容器，软件包必须恰好位于其下一级。

2. 注册仓库内软件包 — 仅在官方单仓库中，严格按照目标检出版本中的开发指南，将软件包添加到 Host 或 Client 聚合项中。普通软件包只能属于一个聚合项。不要未经核对目标版本就照搬历史例外或文件列表。外部插件绝不能修改 Harness 根配置。

3. 创建外部软件包 — 保留现有的软件包管理器和构建系统。对于新插件，遵循外部命名政策，并包含经过验证的 dsh-plugin.naming.json；对于现有插件，不要擅自重命名公共接口。确保 main、types、exports、files、可选的 bin、打包组合或 Profile 元数据与打包后的 tarball 保持一致。明确声明每项运行时依赖，并在开发依赖中镜像声明编译所需的 DSH peer 依赖。不要仅仅因为仓库内模板如此，就将可发布的外部插件设为 private，或为其指定 workspace 版本范围。

4. 选择软件包拓扑 — 对于可替换的能力，仅当服务定义、提供方和使用方会独立演进时，才将它们拆分为独立软件包。单一用途的插件应保留在一个软件包中。

5. 编写仓库内软件包 README — 仅在目标单仓库有要求时，优先介绍软件包专属的服务 API、配置、事件、扩展点和设计说明。README 末尾应采用目标检出版本中的规范“Model Experience”顺序和“Known Limitations”章节。将每个直接、条件式、有上限、生命周期或辅助模型接口分别放在独立的 H3 下，并包含以下三个 H4 章节，每节各有一个说明段落。引用由软件包拥有的稳定文本。对于工具 Schema 接口，只描述生成的工具目录中尚未包含的差异。在“KV Cache Impact”下，区分仅追加增长、稳定的重复前缀、对先前请求令牌的替换，以及独立的模型请求。随后列出会使复用失效的软件包变更。

   ## Model Experience
   
   ### Request Surface and Activation Conditions
   
   #### What the Model Sees
   
   Name the exact data-dependent field, link to the generated catalog with an anchor, or introduce the verbatim text below.
   
   ##### Place the Verbatim Field Text Here When Needed
   
   ```markdown
   Copy any stable system-prompt body or other long nongenerated literal exactly from source.
   ```
   
   #### Token Impact
   
   State whether the impact is fixed, conditional, retained, replaced, capped, or has zero direct token impact.
   
   #### KV Cache Impact
   
   Describe append-only, prefix-stable, replacement, or independent behavior, including exact conditions that may invalidate reuse.
   
   ## Known Limitations and Deferred Work
   
   - **Consumer-visible gap** — State the exact missing operation or condition, its consequence, and any maintainer constraint.
   

6. 验证 — 对于新的外部插件，先运行 node <plugin-write-skill>/scripts/validate-names.mjs --manifest ./dsh-plugin.naming.json；仅在采用抗冲突社区配置时添加 --strict。通过后，在网络可用时运行 node <plugin-write-skill>/scripts/query-registry.mjs --manifest ./dsh-plugin.naming.json --harness-version <exact-semver>，并将无法查询的状态报告为未知，而非可用。如果存在代理变量，且 Node 内置的 fetch 无法访问索引，请遵循 references/registry-check.md；不要暗示 Node 20-23 会自动使用这些变量。然后运行下方适用的验证区块、针对性检查，以及变更行为所需的覆盖率门槛。

编写规则

• 将每项注册都视为一种 effect。通过 ctx 辅助方法或带有 disposer 的 ctx.effect() 进行注册，并确保插件卸载时清理所有事件监听器、工具、定时器及其他资源。
• 在有文档说明的扩展点添加新行为。不要修改 agent-loop。
• 为公共服务方法和类型化事件添加带有 @param 和 @returns 的 JSDoc。通过在目标 Cordis Events 接口上进行声明合并来定义类型化事件，并使用 @mode 说明分发模式。
• 不要将可调值硬编码。任何可能因部署环境而异的值，都必须是经过验证且可通过 cordis.yml 更改的 Config 字段。
• 模型看到的所有内容都必须能从会话日志中重建。
• 配置错误必须明确报错。绝不能静默跳过缺失的被引用对象。应在解析器、配置、接线和进程边界进行验证，而不是信任进程内的类型化调用方。

验证

对于官方 Harness monorepo 中的包，请使用目标检出版本中的当前根目录命令。以下名称仅为示例；运行前请确认这些命令确实存在：

pnpm install            # Register the workspace
pnpm run doc-sync
pnpm run constraints && pnpm run typecheck && pnpm run lint
pnpm run build && pnpm run hygiene

对于外部插件，请使用其自身的安装、类型检查、测试、静态检查和构建命令。打包可发布的制品并检查其内容，然后将其加载到运行精确目标 DSH 的隔离 Profile 中。升级时，请冷启动并完成一次“消息 → 工具 → 回复”流程，或等效的核心流程。报告所有尚未覆盖的提供商、操作系统、UI 或凭据边界。

根据更改涉及的范围选择测试：对逻辑进行单元测试；运行仓库的覆盖率门槛；在具备提供商凭据且获准执行时运行真实 API 端到端测试；对模型、协议或用户可见行为使用无凭据快照；对用户可见插件使用真实组合测试。包的 bin 入口还需要在原生 Node 下进行构建制品冒烟测试。按照这些规则完成最低限度且充分的测试集，不要加载其他 Skill。

参见 references/README.md 中的参考资料索引。