# 使用说明

[简体中文](USAGE.md) · [English](USAGE.en.md)

### 峰谷调度如何工作

在 **设置 → 全局会话调度 → 紧急避险** 中打开。默认关闭，偏好在宿主持久保存。

| 时机 | 行为 |
|---|---|
| 峰价 | 拦截全局 `agent/pre-step` 与 `agent/request`，阻止下一步骤继续执行；主代理和子代理均适用。 |
| 谷价 | 放行等待中的原始 continuation，继续原会话，不发送伪造的“继续”提示词。 |
| 用户手动取消 | 保留取消结果，不会在谷价复活已取消任务。 |
| 关闭调度 | 立即释放调度等待中的步骤。 |

已经发出的模型请求或正在执行的工具会完成，然后暂停；这不是撤销请求，也不能追回已经发生的费用。范围为**同一 DSH 服务进程**，不跨机器控制独立 DSH 实例。峰谷时段取当前计价配置与其时区，不以界面语言推断。

本地预览没有连接真实 DSH，因此会标记为预览；正式安装使用真实钩子。宿主缺少必要能力时会显示不可用，而不是假装暂停成功。

### 金额与补给

`total_balance` 是可用余额，`topped_up_balance` 是剩余充值余额，`granted_balance` 是赠金余额；并非历史充值总额。显示货币可独立选择原币种、人民币、美元、韩元或卢布，与界面语言及天气服务地区无关。余额、会话及子任务费用、峰谷汇总、补给进度按最新参考汇率显示约合金额；原始账户数据与结算不变。余额和费用详情中显示汇率来源及日期。会话费用属于依据可核对用量与价格计算的估算，不是官方账单。

默认每累计 ¥0.10 可核对用量进行一次掉落判定，25% 概率成功，成功获得 1–3 件，少量更常见。开启峰价加成后，峰价按双倍进度积累判定次数。实际账单金额不乘倍率。物品可以连续使用；无限模式不扣库存，仍参与随机掉落。预览用量不会产生真实补给。


## 动效与补给

气泡默认停留 5 秒；重新悬浮人物可再次查看。键盘主动聚焦查看不受自动收起打断。

新主会话或子代理首次开始执行时播放吃 Token 动作，读取历史会话不会触发。两种互动模式都按已结算的 DeepSeek 用量费用获得补给。无限模式只增加库存，不因互动扣减；关闭后显示实际数量。新增补给以同一套 SVG 图标依次浮出，短时间同类掉落会合并数量，重载页面不会重播历史奖励。

紧急避险对开启时已经运行的会话也有效。正在请求模型或执行工具的会话显示为“等待安全暂停”，到请求或步骤边界后转为“已暂停”。已发出的请求或工具操作不能撤销，不采用强制中断后重新提交任务的方式伪装为原地续跑。

功能菜单的按钮圆角可在设置中从 0%（正方形）调到 50%（圆形）。悬浮动作完整播放后恢复当前任务状态，快速经过多个按钮只保留最后一个仍在悬浮的动作。峰价获得的小鱼干会散落在人物脚边，最多同时显示 12 条，多余数量合并进奖励提示；几秒后自动收起。静态陪伴和专注模式不播放散落动画。

全球官方 API 的峰谷规则统一以北京时间和中国放假安排为准：周一至周五（排除放假日）09:00–12:00、14:00–18:00 为峰价；周末和中国放假日全天谷价，周末补班也不变。下次切换时间转换为设备当地时间显示。详见 [DeepSeek 官方价格](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/)。

## 任务概览与记账

任务进展用于快速查看状态、目标、计划和结果。子代理按待处理、执行中、已结束排序；文件和工具记录按需展开。面板内可查看 Markdown 结果，仅在宿主提供相应能力时显示文件和子代理入口；不再提供无法精确定位的步骤跳转。

补给按已结算的独立用量记录累计。暂停、刷新、重复事件、跨峰谷时钟变化和历史价格刷新都不会产生新补给。中断时迟到的真实用量仍会结算；其他主会话或子代理继续使用时也会继续累计。所有执行结束或暂停后，清空未播放的奖励动画，库存保留。升级不追溯重发历史补给。

## 会话金额显示

在设置 → 用量与隐私中调整“金额小数位”，支持 0–6 位，默认 4 位。设置同时用于底栏与费用详情，不改变用量计算或补给累计。金额变化时仅更新的数字上下滚动；首次加载、切换会话、切换语言、货币或精度时直接显示，减少动态效果或专注模式下不滚动。费用详情先显示合计，再显示谷价和峰价分项；底栏悬浮仅提示下次切换时间。

## 任务详情分类

任务概览保持可见，下方通过协作、计划、文件、记录四类 tabs 切换。没有数据的类别不显示。每类保留滚动位置和已展开的列表数量；方向键及 Home/End 可切换。任务结果继续在面板内查看。

默认安装不会额外调用模型，但会有本机资源开销。参见[性能、模型用量与测量方法](PERFORMANCE.md)。

任务分类按以下范围展示：协作包含跨轮次仍在执行或等待处理的子代理，以及本轮启动或完成的子代理；计划保留本会话最近一次 `todo/write`，跨轮时标为“最近计划”，新列表（包括空列表）会替换旧列表；文件保留本会话最近 20 个已确认修改的文件；记录展示当前轮的工具操作。继承自其他会话的日志不计入这些分类。

PTC 模式读取 `tool/ptc-dispatch-start` / `tool/ptc-dispatch`，显示 `run_code` 内实际执行的操作，并保留外层错误。文件分类仅收录成功的 `write`、`edit`、`write_file`、`edit_file` 与 `str_replace_editor` 写入操作；读取、失败操作、未知工具及 Bash 输出不作为文件修改证据。无数据的分类不显示。

文件显示相对会话工作目录的路径，项目外文件保留完整路径；打开文件始终使用原路径。计划和文件路径最多一行，消息摘要最多两行，截断后可悬浮或用键盘聚焦查看全文，长提示支持滚动。执行中的计划与操作使用加载图标，读屏仍可获得状态。

顶部显示最近的公开消息，点击可定位到原文。“对话”分类提供每页 30 条的消息索引，可继续读取更早消息。定位使用消息身份和事件位置，必要时通过宿主加载历史；切换会话或关闭面板会取消后续定位。不同版本宿主缺少相应能力时会保留内容并提示，不会猜测相似文字的落点。

计划 Tab 显示“已完成 / 总任务”，取消项不计入总数；不再额外显示进度条。数据来自真实 `todo/write`，不是按时间估算。面板打开期间约每 1.5 秒刷新，隐藏页面暂停轮询。更新保留所选分类、已加载的消息页和分类滚动位置。

从任务面板进入子代理后，面板保持打开，左上角可返回上级会话，并恢复先前的分类和浏览位置。消息定位后，重新打开任务面板可返回跳转前的阅读位置；原消息已不可用时会提示，不会猜测其他落点。返回记录仅存在于当前页面中，手动切换到无关会话不会使用旧返回路径。

### 任务入口、长文本与称呼

功能菜单新增“任务进展”，直接打开面板，默认启用；可在“功能菜单 → 任务入口”隐藏。它遵守已有按钮数量上限，放不下时进入“更多”。悬浮人物的状态气泡仍可使用。

只有一个分类时，面板显示小标题；多个分类才显示标签栏。文件路径和计划用满可用行宽后单行省略，对话保留两行。只有实际被裁切的文字才提供全文提示；容器缩放、字号或字体加载变化后会重新测量。列表按需展开，对话每页加载 30 条。

“陪伴与动效 → 称呼”优先于自动称呼。留空时使用运行 DSH 的系统账户名；账户不可读取或属于通用服务账户时，使用当前语言的亲切称呼（中文为“小可爱”）。不会读取 Git 作者名。远程部署时读取的是服务端账户，建议自行填写称呼。称呼仅用于本地界面，不发送给模型；最长 24 个字符（按完整字形计数）。

“情境回应”控制低频的余额、任务时长和空闲反馈。余额档位继续按接口原币种判断，不受显示汇率影响；未知币种不推断高低。快速完成会开心跃动，长任务结束会伸懒腰。关闭情境回应、专注模式、静态陪伴或切到后台时，不播放这些反馈。历史完成记录不会重新庆祝，也不增加模型调用、费用或补给。


### 持续互动与会话费用

养成面板中的四种互动使用后保持打开。没有时间冷却，也不等待动画结束。连点请求按顺序处理；饱食封顶后仍可投喂。库存不足、任务忙碌或网络失败时停止未发送操作，避免继续扣除。网络重试沿用原始请求编号，避免重复扣除。面板打开时养成值持续更新；余额和天气按缓存策略刷新，保留展开位置和已显示的数据。

补给进度环位于输入框下方金额右侧，使用所有会话的已结算补给数据。进度柔和推进，每次新增能量切换色调，跨圈先完成再续接；批量到账合并动画，后台和减少动态效果时直接更新。无限互动仍累计进度。

当前会话费用包含它及其子代理的用量，递归统计嵌套子代理。谷价、峰价和合计都包含子代理；“其中子代理”是合计内的组成部分，不能再相加。继承的历史事件与重复子代理引用不重复计费。已释放子代理通过只读历史读取，无法核对的记录会显示为部分统计。后台费用汇总更新需要正常重启 DSH 后启用。

自动同步价目默认关闭。已主动保存的设置继续保留。文件列表显示名称、扩展名标签和打开箭头，悬浮显示原始完整路径。当前 DSH 内置 `.md` / `.markdown` 预览，鲸鱼娘沿用宿主自动选择，不注册重复 Markdown 处理器，也不覆盖其他插件或用户选择的查看方式。


### 配置随机掉落

打开“设置 → 随机掉落”。修改会立即回显，停止连续调整约 400 毫秒后自动保存并生效，无需点击应用。保存中仍可继续编辑，旧响应不会覆盖新值；无效范围或保存失败会提示，失败时可重试：

| 设置 | 默认 | 可调范围 |
|---|---|---|
| 判定额度 | ¥0.10 | ¥0.01–¥100.00 |
| 掉落概率 | 25% | 0–100% |
| 最少 / 最多件数 | 1 / 3 | 1–20，最少不大于最多 |
| 小鱼干占比 | 50% | 0–100%，剩余概率由三种互动均分 |
| 峰价加成 | 开启 | 开关 |

每次判定独立，可能落空，没有强制保底。成功后先抽数量，再逐件抽类型，可能获得混合物品；数量范围内每增加一件，其相对权重减半。修改规则保留当前进度比例和库存，只作用于后续记账；不会重抽历史消费。修改其他窗口已更新的规则时会提示冲突。进度环表示距离下次判定的进度，不代表必定掉落。

连续使用没有计时限制；网络请求串行执行，最多保留 20 个待处理点击。断网或库存不足时取消未发送点击，已发送请求使用原编号重试。动画只保留一次后续回应，避免连点造成长时间积压。

外观和字号等本地设置即时生效，写入浏览器存储采用 200 毫秒防抖；关闭页面前刷新待保存内容。控件采用统一右列宽度，单位显示在输入框内部。安装和更新见 [INSTALL](INSTALL.md)，数据范围见 [PRIVACY](PRIVACY.md)。


### 外观

主题默认为**自动**，与 DSH 当前外观同步，宿主切换主题时即时更新。也可单独指定浅色或深色。语言和减少动态效果的设置独立生效。

## 语言、货币与天气地区

汇率使用 [Frankfurter v2](https://frankfurter.dev/) 的公开每日参考数据，无需 API Key。“界面语言”“显示货币”和“天气服务地区”独立保存。语言支持跟随系统、简体中文、英语、韩语和俄语；货币默认原币种，可单独选择 CNY、USD、KRW、RUB。天气服务默认按设备时区选择，也可指定中国大陆或国际。旧设置保留原语言，新增设置使用上述默认值。换算只在显示层发生，每次都从原始金额计算，不反复转换已舍入的金额，也不合并不同币种账户。

宿主按需请求固定货币表，15 分钟缓存、并发合并、5 秒超时、失败后至少 60 秒再试。浏览器共用一个订阅，后台页面停止刷新；没有模型调用。超过 7 天的参考汇率不再用于换算。短暂故障使用带日期的旧数据并提示；无有效汇率或未知源币种时明确显示原币种。首次加载与服务重启可能先显示原金额，汇率到达后自动更新。

预算和掉落判定额度的**输入项仍明确标为 CNY**，旁边提供所选货币的约合金额；显示币种变化不会改写这些结算阈值。会话费用小数位仍遵循用户设置。可在宿主插件配置设置 `exchangeRates.enabled: false` 关闭外部汇率请求。离线预览默认不访问汇率服务；测试真实汇率可用 `PREVIEW_OFFLINE=1 PREVIEW_EXCHANGE=1 npm run preview`（仍不读取账户密钥）。

### 补给圆环与桌面奖励提示

圆环满格代表一次掉落判定，不代表必定获得物品；实际概率以补给设置为准。只有服务端累计获得数量增长，人物才显示对应物品与数量。人物短暂隐藏时，待展示的物品奖励按种类合并保留（最多四种），恢复可见后继续显示；已播放但被隐藏中断的提示会重新合并，不重播首次加载前的历史库存。

奖励提示只显示实心物品与加粗数量，没有背景、边框或阴影，停留约 3 秒。图标随人物大小缩放在 18–34px，数字在 14–24px。独立桌面实例配合隔离模拟服务已验证可显示物品 ×N；测试不修改正式库存或概率。

### 人物与菜单尺寸

在「设置 → 外观 → 功能菜单」选择「独立设置」或「跟随人物」。默认按钮为固定 36px，可独立调整至 28–56px；人物大小不会改变面板文字尺寸。尺寸滑块拖动时显示待应用数值，松开后应用，避免面板移动影响滑块取值。

小鱼干数量位于按钮外侧，超过 99 显示 `99+`；悬浮或键盘聚焦可查看完整数量，无限互动显示 `∞`。

### 中国放假日历

内置 2025、2026 年的 [holiday-cn](https://github.com/NateScarlet/holiday-cn) 公告数据（MIT），全球用户共用中国日历。宿主启动时检查当年和次年数据，成功后每 24 小时更新；失败至少间隔 1 小时重试，单次请求最多 5 秒，CDN 不可用时尝试 GitHub 源。次年公告可覆盖上一年 12 月。更新后费用估算和谷价调度同步生效。

日历缓存在 `~/.dsh/dsh-kujira/holidays.json`（自定义 inventory 或 holidayCalendar 目录时随该目录保存）。断网保留已核对数据；空的未来年份文件不会覆盖有效日历。缺少当年安排时，暂用周一至周五时段规则，调度设置显示日历缺失提示。设置 `holidayCalendar.enabled: false` 可禁用联网更新，继续使用内置数据；预览默认禁用。显示货币和语言不会改变日历、时区或结算规则。

## DeepSeek Harness 更新

设置 → 服务 → DeepSeek Harness 更新：默认每日检查官方 npm 注册表，无模型调用。发现新版本后，设置按钮显示提示点，服务标签显示“更新”。可关闭自动检查，或手动检查（最短间隔 1 分钟）。检查失败保留上次结果，自动重试至少间隔 1 小时。

默认跟随当前通道：alpha 安装继续关注 alpha，并同时比较官方 latest；也可单独选择 latest 或 alpha。自动更新仅提供更高版本，不因 latest 标签较旧而降级。需要回退时，展开“历史版本与回退”，从官方已发布、未弃用的版本中选择，点击“切换到版本号”。上一个安装版本会优先列出并保留记录；切换版本也要求没有运行中任务。回退保留会话和配置，旧版可能不兼容新版配置。版本状态区分别显示当前运行版本和安装完成后待重启的版本。

一键安装支持当前运行实例对应的 npm/pnpm 全局安装，使用原包管理器安装已展示的精确版本，来源固定为 `@deepseek-ai/dsh` 的官方 npm 注册表，并检查 Node 引擎要求。源码、npx 临时安装及无法识别的安装方式只检查版本，保留原更新方式；本功能不调用 sudo，也不修改账户、插件配置或会话文件。

只有在运行 DSH 的电脑上打开 localhost/127.0.0.1 页面、且当前无运行中任务时，才能点击安装。安装超时为 10 分钟，同一用户的更新使用文件锁串行执行；退出 DSH 会取消正在执行的更新进程。成功后需正常重启 DSH，再刷新浏览器，界面不会假装运行中的旧进程已经升级。

检查设置保存在 `harness-update.json`（默认 `~/.dsh/dsh-kujira/`，跟随自定义 inventory 目录）；可在宿主配置设置 `harnessUpdate.enabled: false` 完全禁用该功能。预览默认禁用联网检查；`PREVIEW_UPDATE=1` 只启用真实版本查询，始终禁止系统安装。

### Alpha 输入框布局

兼容 alpha 将原生上下文圆环移入底栏后的结构：从左到右依次为上下文圆环、模型选择器、发送／执行按钮，原生点击与详情面板保留；底栏统计居左，费用及补给居右并垂直居中。适配不移动 React 管理的节点，卸载和切换会话时恢复布局属性。窄窗口中的版本检查、安装和回退按钮使用紧凑尺寸。