# 安装与移除 / Install and remove

`dsh-bug-gps@1.0.0` 已在官方 npm registry 公开，默认使用已发布版本安装。固定 Git 和 GitHub Release 安装包作为备用来源。[发布清单](https://github.com/lijiaqi-AI-Product-Manager/dsh-bug-gps/issues/4)记录当前状态，[运行依据](verification/1.0.0/README.md)区分安装、工具执行与其他验收范围。

## 从 npm 安装

```bash
dsh plugin --profile web add dsh-bug-gps@1.0.0

dsh --profile web --dump-config
```

重启同一实例，在目标 Git 项目调用 `buggps_status`。无界面实例改用 `--profile headless`。正式 registry 的匿名下载、两个全新 Profile 的安装/移除与官方 Web 完整流程见 [npm 发行记录](verification/1.0.0/npm.json)。

## 固定源码

先准备 DSH 0.2.1-rc.5、Git、PATH 中的 pnpm ≥10，以及系统 Edge 或 Chrome。独立 CLI 最低 Node 20.0.0 已实测，DSH 宿主验收环境使用 Node 24；不将前者当成所有宿主组合的保证。

下面以 `web` 为例；使用无界面实例时，将两处 Profile 名称改为该实例实际使用的 `headless`。桌面实例的 Profile 和内置版本应独立确认，当前记录不替代桌面验收。

```bash
dsh plugin --profile web add 'git+https://github.com/lijiaqi-AI-Product-Manager/dsh-bug-gps.git#c48aa094b6b32731d517fb0026cceccdae60e117'
dsh --profile web --dump-config
```

确认输出包含 `dsh-bug-gps` 配置层，重启对应实例，在目标 Git 项目中调用 `buggps_status`。完整任务还需要应用开发服务和 `buggps.config.json` 的独立 `serve` 配置；配置层出现只表示配置写入，工具注册及任务执行分别确认。

本地 checkout 或当前 `npm pack` 得到的 `.tgz` 也可作为 `add` 的来源。npm 安装命令见首节；备用来源的运行环境要求相同。

## 升级已有场景

当前采集协议为 `buggps.capture/v2`，检查器为 `buggps.oracle/v10`。升级后应重新录制旧的浏览器草稿；不通过补填版本号迁移。录制中的全部文本、输入值和可见性检查保存原始观察状态，锁定时必须逐次匹配，防止遗漏操作后绑定另一种失败。无法定位的动作、采集异常或写入确认失败会保留为录制问题，草稿不可锁定。

当前重放上下文只包含原始顶层页面。iframe 或额外标签页中的动作会使草稿不可锁定，不会映射到主页面的同名控件；需要先将场景限制在同一顶层页面。支持范围外的交互不能作为已验证结果继续使用。

旧的已锁用例与运行记录继续保留，但不能直接作为新检查器下的当前修复依据。结构化编写的草稿仍可使用原有格式，验收条件由项目需求确定。完整流程应重新建立原代码失败、候选通过与新建原代码对照，不降低断言或跳过失败步骤。

## 移除

对安装时使用的同一个 Profile 执行：

```bash
dsh plugin --profile web remove dsh-bug-gps
dsh --profile web --dump-config
```

确认依赖和配置层移除后，重启该实例。项目中的 `.buggps` 场景、补丁及运行产物继续保留；卸载插件不会替你删除这些项目资料。需要清理时，由项目所有者明确选择具体内容。

## English

Install the published `dsh-bug-gps@1.0.0` from npm using the first command above. Pinned Git and GitHub Release sources remain available as alternatives. The release checklist records availability; Git, tarball and registry installation evidence have separate scopes. Use the Profile your running instance actually owns; restart it after adding or removing the plugin. Git, pnpm ≥10, a system Chrome/Edge and an application serve configuration are required.

The standalone CLI was checked at Node 20.0.0; the DSH host checks use Node 24. A configuration layer in `--dump-config` confirms configuration, while `buggps_status` and the complete task check tool registration and execution. Desktop acceptance remains separate.

Re-record older browser drafts after upgrading to capture protocol `buggps.capture/v2` and evaluator `buggps.oracle/v10`; adding a version field is not a migration. Recorded text, values and visibility must match their captured original states before locking. Missing action targets, capture errors and unconfirmed writes keep a draft incomplete. Preserve earlier cases and records as history, then establish fresh evidence with the current evaluator. Structured authored cases retain their existing format.

Replay currently addresses the original top-level page. Actions inside an iframe or an additional page make the recording incomplete; they are never mapped to same-named controls on the main page. Keep a recorded scenario in one top-level page.

The commands use `web`; use `headless` instead for a headless instance. Remove the package from the same Profile with `dsh plugin --profile web remove dsh-bug-gps`. Verify that its dependency and configuration layer are gone, then restart. Existing project cases, patches and run artifacts remain in the project. The [historical evidence](verification/1.0.0/README.md) identifies its own source and distinguishes installation, execution and directory admission.