# 使用指南

本页说明安装、操作、配置与升级。产品介绍见[项目首页](../README.md)，开发和验证见[开发指南](development.md)，行为契约从[文档索引](README.md)进入。

## 安装到 Desktop

支持 **DSH 0.2.0-rc.2、0.2.1-alpha.1、0.2.1-rc.1、0.2.1-rc.2、0.2.1-rc.3 和 0.2.1-rc.5**；其他版本未声明兼容。

在 0.2.1-rc.1 / rc.2 / rc.3 / rc.5 中，从左下角账号菜单（未登录时显示“更多”）选择“设置”，再进入“桌宠”；0.2.0-rc.2／0.2.1-alpha.1 从侧栏“设置”进入。

### 在 Harness 中从 npm 安装

打开侧边栏 **插件 → 添加插件**，在「包名或地址」输入 **`@takboo/dsh-coopanion@0.4.17`**，点击安装，再启用 `dsh-coopanion`。显式版本可以避免发布首日的裸包名解析回退，原因见下方。安装方式见 [Harness 官方插件管理说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-plugin-manager/README.zh.md#安装一个组合包)。

### 安装版本与发布时间保护

pnpm 11 的 `minimumReleaseAge` 默认为 1440 分钟（24 小时）。详情页可以从 npm metadata 显示最新版本，但仅输入 `@takboo/dsh-coopanion` 时，安装解析仍可能跳过等待期内的新版本。见 [pnpm 官方说明](https://pnpm.io/supply-chain-security)。

安装后请核对日志中的实际版本与上方精确版本一致。自定义启用了 `minimumReleaseAgeStrict` 时，按安装器提示确认该精确版本或等待保护期结束。发布时间保护与 DSH 宿主兼容校验分别生效，无需全局关闭保护或豁免不兼容的旧版本。

### 通过 dsh 命令行安装

**Desktop：** 使用 Desktop 自带的 `dsh` 命令。先启动 Desktop 一次初始化 profile，完全退出应用，再执行：

```bash
dsh plugin --profile desktop add @takboo/dsh-coopanion@0.4.17
```

npm 安装的 dsh 不能管理 Desktop 所拥有的 profile；若系统找不到 Desktop 的命令，先在 Desktop 的菜单栏中使用 **Manage dsh command／管理 dsh 命令** 安装命令入口。

**本机 Web profile：** 使用 npm 安装的 dsh 时，向实际使用的 profile 安装。例如默认 `web` profile：

```bash
dsh plugin --profile web add @takboo/dsh-coopanion@0.4.17
dsh --profile web
```

此方式需要本机图形桌面才能显示桌宠，浏览器承载系统通知；其他自定义 profile 将 `web` 替换为实际名称。已有 Host 先停止，再安装并重新启动。

### 通过压缩包安装

下载 [Release](https://github.com/takboo/dsh-coopanion/releases/latest) 的 `dsh-coopanion.tgz`（或对应版本包），在 **插件 → 添加插件** 中填写压缩包绝对路径，安装后启用。自行构建见[开发指南](development.md)；本地 `npm pack` 的文件名包含 scope。

也可使用 Desktop 自带的 CLI，在完全退出 Desktop 后执行：

```bash
dsh plugin --profile desktop add /absolute/path/dsh-coopanion.tgz
```

### 安装完成后

完全退出并重新打开 Harness。首次启动会下载并校验 Electron 44 运行时；在 **Settings → 桌宠** 查看运行状态，打开一段会话后双击角色即可聊天。

Windows 桌宠显示期间会在失去置顶后自动恢复，恢复时不抢当前应用焦点；隐藏或最小化后不会因此重新显示。macOS／Linux 的窗口层级保持原有行为。

### Electron 运行时准备

首次安装或升级 Electron 后，桌宠在独立子进程中下载、校验并解压运行时；准备期间设置页显示“正在启动”，Harness 的窗口、服务和其他插件继续响应，也可随时关闭桌宠来取消准备。准备最多等待四分钟，失败后设置页显示错误；检查网络后点击启动重试。运行时准备完成后才开始原生窗口的 20 秒启动检查。

网络受限时可设置 Electron 支持的 `ELECTRON_MIRROR`，并从设置了该变量的终端启动 Harness。也可完全退出 Harness 后，在实际 profile 目录手动准备（下面以 Windows PowerShell 为例）：

```powershell
$env:ELECTRON_MIRROR='https://npmmirror.com/mirrors/electron/'
node "$env:DSH_HOME\profiles\desktop\node_modules\electron\install.js"
```

使用实际配置的 `DSH_HOME`；CLI 的其他 profile 替换 `desktop`。运行时继续按 Electron 的安装器校验。成功后重新打开 Harness；已准备好的二进制直接复用。自备运行时也可使用 `electronPath` 的绝对路径配置。

## 配置与会话

**Settings → 桌宠** 沿用 Harness 的主题、中英文与系统语言设置。可控制随 Harness 启动、闲时活动、任务通知、系统通知、待处理请求补提醒、等待时间、角色尺寸（90–240）、文字大小（100% / 125% / 150%）和气泡时长（2–60 秒）；数值按 Enter 或离开输入框保存。文字大小选择后立即保存并同步到当前桌宠，独立于角色尺寸，保留当前阅读、草稿与在途发送；旧配置默认 100%。

### 自主陪伴

在 **Settings → 桌宠 → 自主陪伴** 或角色右键菜单中选择“安静陪伴”或“互动陪伴”。默认关闭，停止自主活动；安静模式从小窝沿当前屏幕底部的一段空间慢走、观察、停留并返回，互动模式额外在白天低频邀请，每天最多两次。所有自动日常统一使用 NPC 调度；关闭陪伴后停止自动日常和邀请。

启用自主行为与邀请时使用以下组合；英文界面的开关名称一并列出：

| 设置 | 建议值 | 作用 |
|---|---|---|
| 闲时走动／Roam when idle | 开启 | 当前也是自主行为和邀请的总许可；关闭后即使选了互动陪伴也不会自动活动或邀请 |
| 自主陪伴／Companionship | 互动陪伴／Interactive | 开启新日常与低频邀请 |
| 本地诊断／Local diagnostics | 仅需外部采样时开启 | 允许读取状态；开关本身不启用自主行为 |

旧 `dailyRhythm` 设置和旧随机漫游已移除。旧配置中的 `dailyRhythm` 不再生效，也不会自动开启陪伴或邀请；原先使用旧节奏的用户需选择安静陪伴或互动陪伴。

“闲时走动”同时控制自动活动许可。NPC 是唯一的自动日常调度；不自主跑跳、跨屏或沿其他窗口行走。

**Settings → 桌宠 → 小窝横向位置／探索范围** 可调整相对当前显示器工作区的百分比，默认 85%／30%；角色实际边界、尺寸及工作区会进一步收紧范围。底部的浅蓝色椭圆就是小窝标记，点击穿透，尚无实体家具；拖动角色不改变小窝位置。也可从菜单临时隐藏、关闭自动活动或手动拖动；拖出当前活动段后先安静停留，拖回或调整位置／范围后恢复。拖动松手后在新位置放下，不因惯性弹回，也不恢复拖动前的旧路线或首次归位；区域内安静等待后重新安排。正文阅读和手动操作始终优先。

鼠标靠近先停；最近键盘活动时暂停外出和邀请，保留未完成目标。角色始终保持设置中的尺寸，打字、选中、悬停或拖动都不自动缩放；稳定空闲至少 12 秒后重新评估活动。键盘感知包含 macOS 聚合事件时间、Windows Raw Input 通知和 Linux X11／XInput2 适配，辅助进程仅输出 active／idle／unknown；不能区分打字与快捷键，也不读取具体按键或其他应用内容。Windows 需要系统 Windows PowerShell；X11 需要 `/usr/bin/python3`、libX11 与 libXi。Wayland（含 Xwayland）、无图形会话、非交互／远程 Windows、接口或依赖不可用均为 unknown，此时安静停留。macOS 不再将“事件监听授权”误当成聚合时间接口的前置条件，无需先授予额外权限。若辅助进程失效，可关闭再开启陪伴重试；诊断中的 keyboardBackend／keyboardStatus 可区分不支持、缺依赖、失败与过期。物理键盘、跨应用／锁屏场景及资源表现按平台分别验证。

无需 DSH 在前台或先打开会话。新工作、异常和审批优先；已呈现的长期待办保留入口，可允许小窝内安静观察。任务与 NPC 情绪各自保留。关闭闲时走动、用户休息、隐藏、锁屏／休眠及减少动态效果暂停自动路径，宿主退出后桌宠仍退出。显示器工作区变化或几何消息遗漏时，会向原生窗口重新同步；尺寸确认前暂停，确认后恢复，无需重启角色。详见[日常契约](companionship-contract.md)。

在角色上连续轻轻抚摸，或从右键菜单选择“一起活动”；实际完成的互动才计入熟悉度，五分钟内不重复增长，每天最多三次。跨至少三天累计六次会解锁挥手后的爱心招呼，缺席和忽略不会扣分。角色更新或换配色不重置，换角色各自保存。菜单可查看相处进展。

邀请可选择“一起活动／稍后／今天安静”，十秒不回应便自然结束。稍后至少等待一小时，今天安静跨重启保留，菜单可恢复邀请；它们不影响任务通知。进度无法保存时菜单会提示，原工作功能仍可使用。详情见[陪伴契约](companionship-contract.md)。

桌宠意外退出后按 1、3、10 秒间隔最多自动恢复三次，连续稳定运行 60 秒后清零。设置页显示等待自动恢复状态、恢复次数和诊断，可随时关闭或在失败后手动重启；主动关闭不触发恢复。隐藏的角色恢复后仍隐藏，关注会话、完整结果、未读和有效待办保留，旧结果不再次主动提醒。窗口内草稿与阅读位置会随进程退出丢失，恢复不会重发聊天或任务。缺少图形环境、无效运行时路径或未确认清理的进程直接反馈错误，详见[恢复契约](desktop-recovery-contract.md)。

```yaml
- id: dsh-coopanion
  config:
    autoStart: true
    size: 180
    roam: true
    # 自主陪伴与诊断默认关闭
    companionship: off  # quiet / interactive
    diagnostics: false
    npcHome: 0.85  # 工作区横向比例，0.05–0.95
    npcRange: 0.30 # 活动范围比例，0.10–0.60
    notifications: true
    systemNotifications: false
    reminders: true
    reminderDelayMs: 600000
    bubbleDurationMs: 12000
    # electronPath: /absolute/path/to/electron
```

最终回复气泡与事件互动提示分别显示。回复气泡时长从逐字显示完成后计时，鼠标停留或键盘聚焦时暂停收起；互动提示收起后，未处理的审批和提问仍保留在小信封列表。超过 180 字的回复展示按句子截取的开头（不做模型摘要），可展开完整阅读；原文保留且不截断，完整阅读器不会自动关闭。减少动态效果时禁用闲时活动与逐字显示，保留直接拖动及落地。

桌宠展示普通顶层会话，忽略子代理；首次可用会话成为当前对话，之后保持用户选中的关注会话。启动时从正式列表恢复最近最多 100 个普通会话，冷会话无需先在 Harness 中打开即可续接。发送中保留草稿，收到“已进入收件队列”回执后才清空；失败可重试，同一次提交复用请求 ID。切换关注会话不会改变在途消息的目标；会话缺失、其他进程占用、权限限制或模型不可用会明确反馈。接受不代表任务完成。详见[会话续接契约](session-chat-contract.md)。桌面版通过公开的 `dsh://open` 协议唤回 Harness。多个本机客户端同时连接时，返回请求由首先领取的客户端处理。

## 提醒与系统通知

开启任务通知后，角色显示时用动作、表情和互动提示提醒；输入、阅读或拖拽期间先排队，结束后再呈现。最终回复与未读列表独立保留。审批／提问可预览内容、返回源会话或选择“稍后提醒”；限时提问标记“仍可回答”时，回合结束后仍可处理。

补提醒默认开启，等待时间可设为 1–1440 分钟。新的待处理请求自动补提醒一次；“稍后提醒”按当前等待时间重新计时。处理、取消或销毁会话后撤销该请求的计时。历史恢复保留待处理入口，不重放旧提醒。关闭任务通知会停止主动提醒，保留会话状态和未读回复。

系统通知默认关闭。在 **Settings → 桌宠 → 提醒与通知** 开启后，点击 **申请／刷新权限**，隐藏运行中的角色，再发送 **测试系统通知**。Desktop 使用 DeepSeek Harness 的应用身份，本机 `dsh web` 使用浏览器身份；点击通知请求打开源会话。角色关闭、启动中、失败或锁屏／休眠期间暂停主动投递。

网页权限“允许”、已请求和收到显示回执分别表示不同步骤；系统送达需在通知中心核对，并点击检查源会话。macOS 在 **系统设置 → 通知 → DeepSeek Harness** 管理授权；Windows 在 **设置 → 系统 → 通知**，Linux 在桌面通知设置中管理。权限或客户端不可用时，待处理入口仍保留；恢复显示不会补发旧系统通知。

## 本地诊断与可选采样

在 **Settings → 桌宠 → 本地诊断** 提供默认关闭的开关。开启后允许独立采样器读取有限的活动／邀请、队列和存档规模，不上传数据或读取聊天正文。它与自主陪伴独立；观察自主活动前先核对上方开关组合。关闭诊断清空诊断计数并撤下接口，不清除关系存档。

macOS／Linux 可直接运行包内的 Node 脚本，无需开发环境或调试端口。Desktop 默认安装路径示例：

```bash
node "$HOME/.dsh/profiles/desktop/node_modules/@takboo/dsh-coopanion/scripts/sample-companion.mjs" --list
node "$HOME/.dsh/profiles/desktop/node_modules/@takboo/dsh-coopanion/scripts/sample-companion.mjs" \
  --output "$HOME/dsh-companion-samples/trial-unique" --seconds 600 --interval 30 --window 60
```

输出目录须尚不存在。发现多个实例时加入 `--instance <list 显示的实例>`，避免混入测试 profile。采样不操作鼠标、不抢焦点、不截图、不防休眠；重启、休眠缺口和关闭诊断会分段记录。关闭接口时采样器可等待恢复，按 Ctrl+C 结束并写报告。日志默认上限 128 MiB，达到后明确停止，不静默丢弃记录。

上例是可选的十分钟工程采样，每 30 秒一条，首／末窗口各 60 秒，不等同于两小时资源验收。脚本默认间隔为 10 秒，默认时长七天仅是工具参数，体验验证无需采用它。`--seconds` 使用进程的单调时钟；跨系统休眠时墙钟结束可能延后，固定日历截止可增加 `--until <含时区的未来 ISO 时间>`，包括接口不可用时也到期结束；休眠跨过截止则在首次唤醒后停止。前台终端退出或系统重启后不保证继续运行，长时工程任务需独立托管并核对进程；不为此阻止正常休眠。

锁屏和休眠状态分别记录，启用诊断后固定事件计数可识别采样间隔内的锁屏、解锁、休眠与唤醒；缺口仍独立结算，计数不提供精确事件时间。原始数据为 `samples.ndjson`，数据可读时约每分钟更新 `progress.json`，接口不可用等变化写入 `events.ndjson`，结束报告为 `summary.json`。日常模式的 `recorded` 只表示数据已记录；关闭 `roam`、陪伴模式未开启或持续工作占用的时间不能作为自主陪伴有效体验。采样是可选的工程诊断；自然体验通过实际使用和反馈判断，资源报告不能替代体验。Windows 通过命名管道提供诊断接口，独立 OS 资源采样尚未支持。数据范围及鉴权见[诊断契约](diagnostics-contract.md)。

## 新角色

右键角色 → **换个模样** → **导入角色包**，选择包含 `figure.json` 的 API 2 ZIP。预览、试播动作、选择配色或搭配，再点击 **使用角色**。删除正在使用的自定义角色会恢复内置大肥鱼。

`examples/star` 是基于上游 `kit.createBody()` 的最小 SVG 角色，具备共享动作、表情、说话和拖拽。复制目录、修改 id 和素材后打包：

```bash
npm run character:pack -- examples/star paper-star.zip
```

完整工厂接口、资源规则、动作映射及换装说明见 [角色对接文档](characters.md)。内置大肥鱼的 `web/upstream/whale/figure.json` / `model.json` / `figure.js` 展示网格角色的完整实现。内置角色的 id 为 `whale`。

## 破坏式更新

当前版本已移除旧 Canvas 关键帧引擎、`dsh-character` v1 协议、`.dshpet` 包、旧 schema 和转换工具。旧角色不能直接加载，也不提供旧引擎兼容模式；需要重新制作或导入 API 2 包。

桌面版改用独立数据目录 `figures-v2`，旧角色选择恢复为内置大肥鱼。旧 `characters` 数据不会被读取；不再需要时可自行删除。Harness 的会话与配置不受角色数据重置影响。
## 回复、未读与会话保护

桌宠不作出审批，也不单独收集 API Key。聊天始终发给明确选中的关注会话，新建会话和后台任务不会自动切换目标。关注会话进行中时优先展示它的动作；空闲时用动作反映后台工作或确认 / 异常。状态栏图形优先提示任一会话的确认 / 异常，菜单显示详情。

信封直接打开回复与待办收件箱：同一会话的多个未读回合合并展示最新回复，未读数量按会话计算。只有一份回复时展开全文；多份回复显示摘要和各自的 **继续对话 ↗**（在桌宠输入框继续来源会话），审批、提问及异常提供 **去处理 ↗**。全文支持 Markdown 标题、粗体、列表、表格和代码块。阅读不会切换正在聊天的会话；收件箱阅读器可连续读不同会话的结果，并返回收件箱查看新内容。正在阅读的回复不会被新结果替换。保留最近 200 份完整结果，优先淘汰已读；只有本次 Harness 运行中实时完成的回复计入未读，打开历史会话或重启 Harness 不会把旧回复重新标为未读。重启后原始对话仍由 Harness 保存；任务动画根据当前 Agent 的运行状态恢复。

从回复选择“继续对话”或在会话列表切换目标后，输入和“打开源会话”保持最近一次明确选择，等待 Harness 确认；较早的已读或状态更新不会把目标退回旧会话。目标消失时采用 Harness 的实际可用列表。

回复气泡展示或自动收起、查看收件箱摘要及收起收件箱均不会标记已读；主动展开阅读、关闭单份回复气泡或通过该回复回到源会话时，确认展示时合并的未读回合。阅读期间新到的回合继续保留未读，旧回合的完整结果仍可通过历史导航查看。通用异常／暂停项点击“去处理／Take a look”后，会清除该轮的信封条目与持续悲伤／等待神态；相同快照不会恢复，新异常仍会提醒。任务的原始失败／暂停事实保留，查看回执只在当前桌宠窗口运行期有效。审批与 AI 提问由 Harness 的实际答复、决定或取消结果结算；查看、收起互动提示或打开源会话均不会代替处理请求。