# 使用指南

安装后的操作、设置及故障边界在本页维护。npm／Release 当前分发版与本地候选的身份见[文档索引](README.md#当前交付)；下文单独标注默认关闭的试用功能。产品介绍见[项目首页](../README.md)，开发和验证见[开发指南](development.md)。

## 安装到 Desktop

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

### 在 Harness 中从 npm 安装

打开侧边栏 **插件 → 添加插件**，在「包名或地址」输入 `@takboo/dsh-coopanion`，点击安装，再启用 `dsh-coopanion`。输入框填写包名即可；若需固定版本，可填 `@takboo/dsh-coopanion@0.4.10`。安装方式见 [Harness 官方插件管理说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-plugin-manager/README.zh.md#安装一个组合包)。

### 通过 dsh 命令行安装

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

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

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
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 → 桌宠** 查看运行状态，打开一段会话后双击角色即可聊天。

## 配置与会话

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

**日常陪伴节奏** 默认关闭，旧配置沿用原有闲时动作。开启闲时走动及此偏好后，按系统本地时间在 07:00–22:00 每 45–90 秒尝试现有轻动作，夜间每 2–4 分钟仅轻点头或坐下；缺少动作时保持待机。任务、待办、阅读、输入、拖拽、用户休息及减少动态效果始终优先，占用解除后重新等待，动作结束恢复当前神态。偏好立即同步并持久保存，不增加模型请求或通知，详见[日常节奏契约](daily-rhythm-contract.md)及[本地验证边界](evidence/m6/README.md)。

<a id="自主陪伴p1-候选功能尚未发布"></a>

### 自主陪伴（P1 试用功能）

在 **Settings → 桌宠 → 自主陪伴** 或角色右键菜单中选择“安静陪伴”或“互动陪伴”。默认关闭，沿用原有节奏；安静模式从小窝沿当前屏幕底部的一段空间慢走、观察、停留并返回，互动模式额外在白天低频邀请，每天最多两次。新模式开启时接管闲时动作，关闭后恢复原日常节奏配置。

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

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

“闲时走动”同时控制自动活动许可。新模式独占调度，不再并行运行旧随机漫游；不自主跑跳、跨屏或沿其他窗口行走。

**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 可区分不支持、缺依赖、失败与过期。macOS 本机输入面板初验已通过；Windows／Linux 物理键盘、跨应用／锁屏场景及各平台资源仍需分别验证。

无需 DSH 在前台或先打开会话。新工作、异常和审批优先；已呈现的长期待办保留入口，可允许小窝内安静观察。任务与 NPC 情绪各自保留。关闭闲时走动、用户休息、隐藏、锁屏／休眠及减少动态效果暂停自动路径，宿主退出后桌宠仍退出。详见[日常契约](companionship-contract.md)与[本轮边界](npc-daily-life-plan.md)。

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

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

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

```yaml
- id: dsh-coopanion
  config:
    autoStart: true
    size: 180
    roam: true
    dailyRhythm: false
    # 0.4.10 试用配置（默认关闭）
    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 在桌面通知设置中管理。权限或客户端不可用时，待处理入口仍保留；恢复显示不会补发旧系统通知。

## 本地诊断与试用采样

0.4.10 在 **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 "2026-10-19T09:00:00+08:00"`（换成实际未来时间），包括接口不可用时也到期结束；休眠跨过截止则在首次唤醒后停止。前台终端退出或系统重启后不保证继续运行，长时工程任务需独立托管并核对进程；不为此阻止正常休眠。

锁屏和休眠状态分别记录，启用诊断后固定事件计数可识别采样间隔内的锁屏、解锁、休眠与唤醒；缺口仍独立结算，计数不提供精确事件时间。原始数据为 `samples.ndjson`，数据可读时约每分钟更新 `progress.json`，接口不可用等变化写入 `events.ndjson`，结束报告为 `summary.json`。日常模式的 `recorded` 只表示数据已记录；关闭 `roam`、陪伴模式未开启或持续工作占用的时间不能作为自主陪伴有效体验。采样是可选的工程诊断，不要求用户运行七天、填表或每日打分；体验按[路线图 P1-J](roadmap.md#p1验收标准)通过短时可见演示和自然反馈判断，明显无感即可停止并进入调整。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`。

## 破坏式更新

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

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

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

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

回复气泡展示或自动收起、查看收件箱摘要及收起收件箱均不会标记已读；主动展开阅读、关闭单份回复气泡或通过该回复回到源会话时，确认展示时合并的未读回合。阅读期间新到的回合继续保留未读，旧回合的完整结果仍可通过历史导航查看。审批与 AI 提问由 Harness 的实际答复、决定或取消结果结算；查看、收起互动提示或打开源会话均不会代替处理请求。