# ADR-001：官方插件扩展边界与交付

状态：已接受；0.3.0 已迁移官方全局面板及可执行清理流程，验收绑定具体归档哈希。

日期：2026-10-18

## 背景

项目目标是在用户已有的 DeepSeek Harness 上安装可组装数字员工插件，并可完整移除。当前演示使用 Harness `0.2.1-alpha.2` 加本地工作区插槽补丁，安装和移除已通过官方 CLI，但不能在未修改的官方发行版上按同样流程交付。用户明确要求统一采用以下边界。

本决策取代旧文档中“先修改并重建宿主，再安装插件”的实施要求，以及把保留全部数据的移除视为完整卸载的表述。现有源码、运行环境和历史记录不在本次规范落地中自动迁移、回滚或删除。

## 决策一：宿主保持官方原版

开发、安装、运行和卸载均不得修改 Harness 源码、构建产物、内置插件或安装目录。禁止通过源码补丁、修改宿主 `node_modules`、运行时 monkey patch、替换或复制宿主私有组件来取得扩展能力。

可以研究官方源码和公开类型；可以由官方插件管理机制更新目标 profile 中本插件的依赖、bundle 选择与配置。不得覆盖其他插件、用户设置或共享数据。正式安装前提是已安装受支持的官方 Harness，不得要求用户准备源码检出或重建宿主。

## 决策二：独立插件采用官方公开扩展契约

“官方插件扩展”指使用官方支持的扩展机制；本项目仍是第三方插件，不宣称 DeepSeek 官方出品或背书。

允许在目标官方版本中已提供的 Cordis 插件生命周期、bundle/profile 配置、公开服务、Remote、技能、工具和 UI 插槽等范围内实现。每个接入点应登记接口标识、官方文档/导出类型依据、支持版本、用途、权限及卸载清理方式。官方尚未提供某个入口时，改用已有公开入口、明确降级或等待上游支持；不得本地给宿主加槽后称其为公开接口。

必要声明应与实际构建产物、依赖和能力保持一致：

| 位置 | 必要声明 |
| --- | --- |
| `package.json` | 包名、版本、说明、许可证、`main`/`exports`、必要类型入口、`files` 打包白名单 |
| 兼容与依赖 | `engines.node`、`engines.dsh`、实际使用的运行时 peer 依赖及对应开发依赖；范围以官方原版验证结果为准 |
| 插件组合 | `dsh.bundle.patch` 与对应的 `cordis.patch.yml`，只声明本插件所需组合 |
| 浏览器与服务 | 按实际需要声明 `dsh.client`、平台、依赖注入、公开服务/工具/技能标识和生命周期 |
| 使用说明 | 支持的 Harness 版本与平台、所需权限、配置项、数据位置、网络/模型调用、重启要求和卸载行为 |

`cordis.patch.yml` 是官方支持的声明式组合层；名称中的 patch 不代表修改源码。它可以加入本插件的配置行，但不能成为覆盖宿主实现、绕过版本检查或扩张权限的途径。

兼容范围不得按“看起来能运行”扩大。对预发布版本明确列出实际验证的版本；版本豁免、忽略检查或放宽 peer 依赖不能作为兼容证明。`engines.dsh` 的版本支持应以所选官方基线的契约为准。

## 决策三：完整卸载是发布要求

安装与移除使用官方插件管理器或 CLI。需要重启宿主或刷新浏览器时，在命令前说明生效边界。可提供两种明确命名的方式：

| 方式 | 结果 |
| --- | --- |
| 保留数据卸载 | 移除插件包及组合注册，释放全部运行能力；明确列出为重装保留的数据和配置 |
| 完全卸载 | 在移除运行能力的基础上，清理本插件专属配置、运行数据、缓存、日志及自建服务；不得遗留无效配置或仍在运行的任务 |

完全卸载流程须可实际执行，不以“可自行删除目录”代替。应维护本插件创建资源及路径的清单，按归属清理；共享配置只删除本插件条目。后台任务须取消或停止，插件注册的 UI、API、工具、技能、订阅、定时器和样式均须释放。停止/清理应可重复执行，不能把已卸载插件在下次启动时自动装回。

用户项目文件、已交付文档与代码、Harness 共享会话和模型凭据、其他插件及其数据保留。若本插件在宿主中创建了专属持久记录，仅通过官方支持的接口管理；无官方清理能力时须说明并列为尚未满足项，不能直接改宿主数据库。任何保留例外都必须在卸载说明与验收记录中列明。安装或升级默认不执行数据清理；本次新增约束也不执行实际卸载。

## 决策四：交付可安装的 npm 插件包

主交付物是 `dsh-plugin-composable-workforce-<version>.tgz`。`.tgz` 是 npm 包归档，可由 `npm pack` 生成，通过 Harness 官方插件管理机制安装；后续如发布 npm，可用包名加版本分发同一类成果。发布 npm 或插件市场不是本次规范的执行动作。

安装包包含插件自身构建产物、manifest、组合配置、所需技能/资源、许可证及必要说明。使用 `files` 白名单控制内容，交付前核对归档。包中不得含 Harness 源码或构建物、源码补丁、本机路径依赖、开发链接、用户配置、凭据、测试数据和运行日志。

每次正式交付同时提供：

1. 插件 `.tgz` 及其 SHA-256 校验和。
2. 安装、启停、升级、两种卸载方式和数据归属说明。
3. 支持的 Harness/Node/操作系统版本、必要声明、变更记录及第三方许可。
4. 与包名、版本、哈希和官方宿主版本绑定的验收记录。
5. 对应的源码版本与构建复现说明，便于审查和维护。

测试环境应直接安装实际归档，不以链接开发目录替代交付验收；接收者无需构建插件或 Harness。

## 发布验收

- 使用未修改的官方发行版和独立临时 profile；记录真实版本、来源、插件归档哈希与执行命令。
- 安装、运行和卸载前后对比宿主程序文件，确认源码、构建物与内置插件未变；记录目标 profile 中仅本插件相关的变更。
- 验证模板/团队、项目绑定、员工执行、权限与交付等发布功能；已降级能力在说明中明确列出。
- 验证移除后入口、API、工具和技能消失，插件任务与自建服务停止，纯宿主及其他插件仍正常工作。
- 分别验证保留数据卸载后的重装恢复，以及完全卸载后的专属资源清理、无无效配置、无自动重装；核对用户文件、成果和共享数据保留。
- 核对归档白名单、兼容声明和许可证；把结果与同一份 `.tgz` 哈希绑定。通过后才标记为符合本约束的正式交付。

## 初始差距（2026-10-18，历史核查）

| 当前事实 | 需要完成的改造 |
| --- | --- |
| `integration/harness-workspace-slots.patch` 给宿主增加两处工作区插槽；`check-host.mjs` 要求这些槽；Client 使用它们 | 迁移至官方原版已有入口，移除源码补丁依赖；重新确定并验证宿主兼容版本 |
| manifest 已有 bundle/client 和 peer 声明，但尚无 `engines.dsh` | 选定并实测官方基线后补齐兼容声明与接口清单，不能先宣称兼容 |
| `scripts/plugin.mjs` 使用官方 add/remove，卸载保留员工、记忆及配置；没有完整清理流程 | 实现并验证两种卸载方式、资源清单和专属清理 |
| 已有 `0.2.1` 归档，其内容包括宿主源码补丁；历史测试以补丁宿主为基线 | 调整交付白名单，生成新归档，在干净官方发行版重做验收；旧包不作为合规成品 |

上述表格记录规范建立时的事实。0.3.0 已移除 Client 对自加工作区插槽的引用，采用官方 `sidebar.panellist/main`，补齐 manifest 和打包白名单，并提供精确归属的 `purge` 流程。最终结果以 [验收记录](../../integration/verification.md) 及其绑定归档为准；历史包和预验包不等同于最终验收。

## 官方依据

- [Harness 0.2.1-rc.2：打包与安装插件](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/docs/user/develop/basic/publish.zh.md)：bundle/profile 区别、组合声明、兼容范围、安装与移除、tarball 分发。
- [Harness 0.2.1-rc.2：CLI 说明](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/apps/cli/README.zh.md)：profile、插件管理与启动机制。

引用该版本的官方文档不代表本插件已在该版本完成兼容验收。