plugin-workflow

协调 DSH 插件生命周期

作为工作流控制器。让用户在执行前选择结果和可选的证明，然后将选定的阶段交由负责该阶段的 Skill，保留一份阶段台账，并返回一份有证据支持的报告。不要将负责该阶段的 Skill 中的详细规则复制到此 Skill 中。

先显示运行前菜单

如果用户尚未明确选择工作流，请在运行任何阶段之前，先展示下方的工作流表和能力表。使用与用户相同的语言，将 health-check 标记为首次运行的推荐选项，并等待用户选择。推荐不等于选择：不要默默默认选择 health-check、开始发现或执行某项能力。

接受工作流编号、工作流 ID 或含义明确的自然语言结果。允许用户在同一条回复中添加或移除能力，例如 3 + docker-smoke + browser-check。简要说明所选能力中哪些为只读，哪些之后会跨越确认边界。

内置规划器会显示相同的确定性菜单，并保持只读：

node <plugin-workflow-skill>/scripts/plan-workflow.mjs
# Equivalent explicit form:
node <plugin-workflow-skill>/scripts/plan-workflow.mjs --menu

如果用户已选择结果并提供了足够的上下文，请保留其选择并继续，无需再次显示菜单。

继续进行只读发现

仅检查足够的上下文，以便明确选择：

1. 阅读仓库说明并检查 Git 状态，不要修改状态。
2. 确认目标是 DSH 单体仓库、外部插件源仓库、已安装的插件，还是已打包的产物。
3. 记录插件源身份、当前 DSH 版本、请求的目标版本、包管理器、可用脚本、插件界面，以及现有的命名声明。
4. 将缺失的输入标记为 unknown。发现阶段不要安装依赖、运行包脚本、启动容器、编辑文件或查询远程注册表。

选择一个工作流

工作流	结果	默认阶段
health-check	只读插件与升级风险报告	发现、可选的 DSH 审计、七触点扫描
upgrade-target	将已安装的插件升级到明确指定的版本	发现、升级、静态检查、回滚记录
compatibility-migration	将插件源适配到精确的 DSH 目标版本	发现、DSH 审计、七触点迁移、静态与运行时测试
test-only	验证现有源代码树或产物	发现、选定的测试级别、报告
naming-registry	验证标识符并检查经过审核的云端注册；可选注册 ID	发现、离线命名、注册表查询；可选注册
package-release	准备并可选择发布版本	发现、必需的测试门槛、打包、消费者冒烟测试、可选发布
full-lifecycle	迁移、验证、命名、打包并可选择发布	按依赖顺序执行所有适用阶段
runtime-debug	诊断并修复 Web Client 运行时行为	运行时诊断／修复、静态、功能与浏览器证明、回滚
heavy-dependency	集成延迟加载的 Web Client 依赖	集成、静态、功能与浏览器证明、回滚、包检查
fleet-sweep	扫描整个已安装插件群，检查其与已升级主机的兼容性	静态与实时插件群扫描、逐个插件修复和发布循环

runtime-debug 和 heavy-dependency 要求使用 web-client 界面。它们也可以作为能力添加到迁移中。fleet-sweep 没有界面门槛，因为插件群同时包含 Web Client 和纯逻辑插件；它会跨越全部三个确认边界，因为它会运行已升级的主机，然后提交、标记并推送每个已修复的插件。只读调查请使用 health-check；仅仅要求诊断某个症状，并不意味着用户选择了修复工作流。

然后让用户添加或排除这些能力。推荐能够证明其所述结果的最小能力集，并说明哪些推荐项目仍未被选择。

能力	选项	默认设置
DSH 版本兼容性审计	dsh-audit	兼容性迁移时启用；否则关闭
七触点插件扫描	touchpoint-scan	健康检查和迁移时启用
类型检查、单元测试和构建	static-tests	源代码变更后以及打包前启用
精确版本 Docker 冷启动	docker-smoke	迁移和候选发布时启用，前提是 Docker 可用
一条真实功能路径	functional-probe	迁移和发布时启用
浏览器验证	browser-check	仅在涉及 Web Client 或 UI 界面时启用
离线命名声明验证	naming-local	对 naming-registry 和新的外部插件启用；否则需选择启用
中央云端注册表查询	registry-query	对 naming-registry 启用；否则需选择启用，且仅限读取
中央云端 ID 注册	registry-register	关闭；本地条目准备会写入注册表检出内容，提交 PR 属于外部发布
回滚演练或方案	rollback	每个写入工作流都启用方案；演练需选择启用
构建并检查软件包制品	package-artifact	软件包、发布和完整生命周期工作流中启用
发布制品或版本	release	除非明确提出外部发布意图，否则关闭
诊断并修复 Web Client 运行时行为	runtime-debug	除非选择启用，否则关闭；需要静态、功能和浏览器验证证据，以及回滚
集成大型浏览器依赖项	heavy-dependency	除非选择启用，否则关闭；需要相同的验证证据以及软件包检查
主机升级后扫描已安装的插件集	fleet-sweep	除非选择启用，否则关闭；需要确认仓库写入、运行时和外部发布权限

用户选择后，使用捆绑的只读规划器规范化所选项。如果其他工具需要生成输入 JSON，请阅读 references/workflow-selection.schema.json。

node <plugin-workflow-skill>/scripts/plan-workflow.mjs \
  --workflow compatibility-migration \
  --include registry-query \
  --exclude browser-check \
  --surface ordinary-plugin

自动化时使用 --format json；若要使用符合该架构的持久化输入，请使用 --selection <selection.json>。不带选择项调用规划器时，它会显示菜单，而不是创建默认计划。规划器会验证冲突和必需依赖项，生成确定性的阶段 ID 和确认边界，并且绝不会执行所选阶段。请将其输出视为初始台账，而非用户批准。

naming-registry 的默认流程会在只读的 registry-query 后停止；绝不会默认包含 registry-register，且后者仍有独立的仓库写入和外部发布边界。用户可以明确排除 registry-query，以进行纯离线运行。不要将查询视为预留，也不要认为本地插件必须注册才能使用。本地插件和中央注册表可以使用相同的显示名称；只有同一运行时界面上的具体标识符才可能冲突。查询完成时，命名负责人必须报告这些确切匹配项以及索引 SHA-256。

构建阶段台账

执行前，为每个选定阶段或依赖项要求的阶段创建一行：

阶段	能力	负责人	状态	证据或阻碍因素
P01	探查	plugin-workflow	selected	目标和源身份

仅使用以下状态值：

• selected：已选择，尚未完成；
• completed：已完成并有证据；
• blocked：已尝试或必需，但无法继续；
• skipped：适用，但有意不执行；
• not_applicable：与检测到的插件界面或工作流无关。

绝不要将不可用或未选择的检查标记为 completed。阶段受阻时，将依赖该阶段的阶段标记为 blocked 或 skipped，并注明依赖原因；随后仅继续执行独立且已获授权的阶段。

将每个阶段交由其负责人处理

执行某个阶段前，先加载并遵循负责该阶段的 Skill。如果负责人不可用，将该阶段标记为 blocked；不要凭记忆重新实现其方案。

阶段	负责的 Skill	边界
已安装版本更新或源代码兼容性迁移	$plugin-upgrade	先检查；确认是否获准修改配置、依赖或源代码
新插件代码、离线命名或注册表查询	$plugin-write	严格遵循目标 Harness 和注册表契约
静态、运行时、Docker、功能或浏览器验证	$plugin-test	选择足够的最低验证级别并保留证据
打包、发布门禁、发布及回滚	$plugin-release	确认发布目标和授权
DSH 主机版本间的证据	$dsh-upgrade-audit	将生成的证据与插件源代码更改分开
Web Client 运行时诊断与修复	$plugin-runtime-debug	确定准确的主机契约并复现失败的交互
延迟加载的浏览器依赖集成	$plugin-heavy-dep	负责分块加载、主机路由、回退和标记处理
主机升级后的全插件集群检查及逐插件发布循环	$plugin-fleet-sweep	在升级后的主机上验证；逐个修复并发布插件，绝不将整个集群作为一次提交处理

每个阶段只指定一位负责人。当运行时调试与依赖集成重叠时，记录诊断出的契约，并由集成负责人使用该契约，而不是另行启动一项相互竞争的重写。各负责人应复用选定的目标版本和源代码身份。如果后续负责人更改了源代码、依赖或打包产物，则使依赖这些输入的先前验证失效，并重新运行验证。

按依赖顺序执行各阶段：

1. 发现并确认源代码身份；
2. 如已选中，则进行 DSH 审计；
3. 升级或实现更改，然后执行选定的运行时修复或依赖集成；
4. 离线命名及选定的注册表查询（naming-registry 默认执行）；
5. 静态测试；
6. Docker、功能和浏览器验证；
7. 发布准备和产物检查；
8. 外部注册或发布。

跳过未选中的阶段，除非某个负责的 Skill 将其列为后续选定阶段的硬性门禁。若如此，将该门禁加入记录表，说明其必要性，并在执行前取得所需确认。

在三个边界内保留授权

按边界归类计划执行的操作，并逐一依据用户请求和更高优先级的指令进行核对。移交给另一个 Skill 时，现有的明确授权仍适用于相同范围；不要仅因负责人变更而再次询问。生成的计划不构成授权，对源代码编辑的授权也不隐含发布授权。只有当所需操作超出已有授权时才询问。

1. 仓库写入：编辑源代码、配置、清单或锁文件前，列出确切文件、预期更改和回滚范围。
2. 依赖与运行时执行：安装依赖或运行非简单的运行时测试前，列出包管理器命令、生命周期脚本风险、容器、服务、浏览器、凭证以及预期生成的输出。普通的只读 Git 和文件检查无需确认。
3. 外部发布：提交、标签、注册表 PR、npm 产物或 Hub／集合更改前，明确指出目标位置和内容，并确认此操作已获用户授权。

如果某个选定阶段跨越多个边界，则在每个边界进入可执行状态时分别进行核对。绝不要仅为完成某个阶段而索取或暴露密钥。

维护并报告证据

每个阶段结束后都要更新台账，包括失败和明确跳过的阶段。保留精确的版本、源 SHA、命令、退出代码、报告路径和未覆盖边界。完成前，确认每项已选能力都有终态。

返回一份报告，包含：

1. 工作流和能力选择；
2. 源与目标身份；
3. 最终阶段台账；
4. 所做更改和创建的提交；
5. 测试和注册表证据；
6. 受阻、跳过和未验证的边界；
7. 仅限此工作流所拥有路径的回滚说明；
8. 发布状态，明确区分本地验证、未找到经审核的注册表匹配项、已审核注册和已发布制品。

不得将部分冷启动概括为功能兼容，不得将注册表中无匹配项说成已预留 ID，也不得将已准备的制品说成已发布。