# 月芒霜鳍鲸（dsh-frostfin）用户手册

> 面向使用者的完整功能指南。安装与项目简介见 [README](../README.md)；本文覆盖装好之后的一切。

## 目录

- [界面速览：东西都在哪](#界面速览东西都在哪)
- [会话面板（本地/远程）](#会话面板)
- [远程会话详解](#远程会话详解)
- [斜杠命令全集](#斜杠命令全集)
- [权限模式怎么选](#权限模式怎么选)
- [模型与 thinking 档位](#模型与-thinking-档位)
- [goal 与 plan](#goal-与-plan)
- [图片、审批与提问](#图片审批与提问)
- [状态条](#状态条)
- [会话生命周期与数据文件](#会话生命周期与数据文件)
- [升级与卸载](#升级与卸载)
- [常见问题（FAQ）](#常见问题faq)

---

## 界面速览：东西都在哪

装上插件后，DSH Web UI 里有三处新东西：

1. **「月芒霜鳍鲸」模式**：新建会话时的默认模式（下拉可切回标准模式=原生 loop）。
2. **「月芒霜鳍鲸」tab（最容易找不到的一个）**：在会话页面**顶部**，和「对话」「轨迹」并排，是第三个 tab。本机/远程的 kimi 会话管理都在这里。
3. **状态条**：输入框下方那一行小字（模型 / thinking / 模式 / git 分支 / 上下文占用 / 目录）。

## 会话面板

「月芒霜鳍鲸」tab 打开后，头部右侧是 **本地 | 远程** 切换。

### 本地视图

列出本机磁盘上的所有 kimi Code 会话（包括你在终端里跑过的），按工作目录分组，按更新时间倒序：

- **接入**：把这个会话接进 DSH（历史回放进会话日志，接着聊）——接入后会话自动归入侧边栏里它工作目录对应的工作区分组（没有该分组就新建一个）；归组修复前接入的会话，在下次「打开」时自动补挂；
- **已接入 → 打开**：跳转回它对应的 DSH 会话；
- **删除**：从磁盘删掉这个会话的全部记录（弹确认，不可恢复）。已接入的会话不显示删除按钮——先删 DSH 侧对应会话；
- 已归档的会话有标记，同样可接入。

注：远程会话目前仍显示在「未分组」——DSH 的工作区模型用本机 realpath 校验会话 cwd，不覆盖远程路径，远程归组需要 DSH 上游支持「远程工作区」概念。

### 远程视图

列出 `~/.ssh/config` 里的全部主机（VS Code Remote 同款读取）。点「连接」做体检（ssh 认证 → tmux → kimi），缺什么会用人话告诉你。连上后按 **工作区 → 会话** 两级展开，可「接入」已有会话、「删除」不要的会话（⚠ 标记的活 TUI 会话不显示删除按钮）；底部一行是**新建会话**：输入远程工作区路径（默认远程 home，`~` 和 `~/xxx` 会自动展开）即可在这台服务器上开一个全新的 kimi 会话。

## 远程会话详解

远程会话的 kimi 进程养在**服务器的 tmux** 里，这带来几个关键性质：

- **断线不死**：本地 DSH 重启、关机、断网，远程进程都不受影响；下次打开会话自动复挂，模式和上下文都在。
- **断开瞬间正在进行的那一轮**会中断（通道死了），会话本身完好，发下一条消息即续。
- **接入/新建/重连**的语义：
  - 接入已有会话 = 新起 kimi 进程 + 把历史回放进 DSH；
  - 断开后再连 = 复挂到还活着的进程（状态全留）；
  - 新建 = 首个 prompt 时才在远程创建会话。
- **死 pane 自愈**：pane 还在但 kimi 死了（崩溃/OOM 等），重连时就绪闸会发现并原位重启 kimi（`respawn-pane -k`），历史照常回放——不用手动清 tmux。
- **双写防护**：接入前插件会探一遍远程 tmux——某工作区有 kimi 在前台运行（多半是 TUI 正开着其中某个会话）时，该工作区的全部会话标 ⚠，点接入会弹确认。探针只看 tmux（裸终端里的 kimi 看不到）、粒度到工作区不到会话（kimi 磁盘上不留活会话标记），所以它是提示不是锁：想用 DSH 接管正开着的会话，仍应先在 TUI 里退出它。

服务器侧的前置：装有 `tmux` 与 `kimi`（并完成过一次 `/login`）。缺的时候面板会明说。

## 斜杠命令全集

命令菜单里按标签区分来源：**[frostfin]** = 插件自带，**[kimi]** = kimi 原生透传，无标签 = DSH 宿主命令。

| 命令 | 来源 | 作用 |
|---|---|---|
| `/frostfin-attach <sessionId>` | frostfin | 接入一个既有 kimi 会话 |
| `/frostfin-sessions` | frostfin | 列出本机可接入的 kimi 会话 |
| `/frostfin-mode <default\|plan\|auto\|yolo>` | frostfin | 查看/切换 kimi 权限模式 |
| `/frostfin-thinking [档位]` | frostfin | 查看/切换 thinking 档位（档位集合以 kimi 当前模型为准，如 off/low/medium/high/max） |
| `/frostfin-plan` | frostfin | 一键进入 kimi 的 plan 模式（引擎级只读） |
| `/yolo` `/auto` | kimi | 模式快捷键（= /frostfin-mode yolo/auto） |
| `/compact` `/status` `/usage` `/mcp` `/tasks` `/help` | kimi | kimi 内建命令，原样透传执行 |
| `/goal` | DSH | 目标模式，对 kimi 会话有效（宿主层轮次驱动，卡片可暂停/编辑/删除） |
| `/plan` | DSH | **只对原生 loop 会话有效**；kimi 会话请用 `/frostfin-plan` |

## 权限模式怎么选

**日常开发：`/yolo`**——绝大多数工具自批，只有碰 .env、SSH 密钥、凭据、.git 控制目录时才打断你。模式按会话持久化，DSH 重启也不丢。

- `default`：每个变更工具都弹窗审批。注意 DSH 弹窗只有"允许/拒绝"，给不了 kimi 的"本会话允许"，所以同类工具会逐次问。
- `plan`（`/frostfin-plan`）：引擎级只读，计划写完交你审。
- `auto`：全部自批，连提问工具都被拒——无人值守场景，配合 `/goal` 跑长任务。

DSH 侧两个开关的注意事项：

- 「Workspace Write」沙箱选择器对 kimi 会话是**摆设**（它管 DSH 原生工具），但**别切 danger-full-access**：它会把会话的 approval policy 改成 never——往 kimi 对话里注入一条英文通知，且在插件 `permission: 'ask'` 时让所有审批被自动拒绝。
- DSH 的 approval policy 只在插件配置 `permission: 'ask'` 时参与应答。

## 模型与 thinking 档位

- 输入框右下的**模型选择器**显示 kimi 的真实模型列表，选即切换；
- DSH 里配置的模型供应商会自动同步进 kimi 的 `config.toml` 托管块（卸载插件时自动摘除）；
- `/frostfin-thinking` 调 thinking 档位；可选档位以当前模型为准（不支持的模型会明说）。

## goal 与 plan

- **goal 用 DSH 的**：`/goal <目标>` 创建后，DSH 负责记目标、注入上下文、在 kimi 每轮结束后自动派下一轮，直到完成或到轮次上限；底部卡片可暂停/编辑/删除。
- **plan 用 kimi 的**：`/frostfin-plan` 进入引擎级只读（Write/Edit 等变更工具被策略层硬拒），写完计划给你审。

## 图片、审批与提问

- **图片**：直接**粘贴**进输入框（没有文件选择器），字节经 DSH 附件存储转给 kimi，真的能被看到。远程会话同样支持（大负载走 fifo 管道）。读不到字节时会放文本占位，绝不静默丢图。
- **审批弹窗**：kimi 的工具审批落 DSH 原生弹窗，弹窗命令预览与工具卡片对齐。
- **提问模态框**：kimi 的 AskUserQuestion 会弹出插件自建的多选模态框（问题原文 + 选项按钮 + 跳过）。跳过的语义是"用户未作答"，kimi 会改用文本追问。

## 状态条

输入框下方一行，从左到右：模型 id / thinking 档位 / 权限模式 / git 分支 / 上下文占用（百分比与绝对值）/ 工作目录 / kimi 进程存活状态。3 秒轮询。远程会话的目录前带 `user@主机:` 前缀（user 来自 ssh 配置的 User 字段，没有就裸别名）。

**断线自动重连**：连接正常时状态条末尾是一个绿点（●，悬停有说明）。当前打开的会话如果已绑定过 kimi 且进程未连接（比如 DSH 刚重启过），状态条会自动发起重连（复挂远程活 pane 或原位重启死 pane），显示"正在重连 kimi…"；失败会 30 秒冷却重试。从未发过消息的全新会话保持惰性启动——打开看一眼不会起进程。

**输入区工具行按钮**：frostfin 会话的输入框工具行多了两个按钮——右侧模型选择器旁是 **thinking 档位**（`thinking: high ▾`），左侧 DSH 访问控制旁是 **kimi 权限模式**（`模式: default ▾`）。点开下拉列出的是 kimi 当前模型上报的真实可选值（有几个列几个），点选即切。

**Kimi Coding 配额**：状态条还会显示订阅配额 `5h:xx% 周:xx%`（5 小时窗与周窗，超 80% 变黄、95% 变红，悬停有绝对用量与刷新时间）。数据源是 `api.kimi.com/coding/v1/usages`，key 从 `KIMI_CODING_API_KEY` 环境变量或 kimi config.toml 的官方渠道条目读取；读不到 key 时该段自动隐藏。注：公开端点目前只有 5h 与周两档，月度口径暂未暴露。

**「文件」tab 与 @ 补全（工作区文件面）**：会话视图多一个「文件」tab——VS Code 资源管理器式的工作区文件树（根就是会话的工作目录，远程会话看的是服务器上的目录），懒加载展开、显示文件大小、点文件复制相对路径。输入框里打 `@关键词` 则弹出「工作区文件」补全组：递归模糊搜索工作区文件（剪枝 node_modules/.git 等重型目录，basename 命中优先），选中插入相对路径——kimi 看到路径会自己 Read（本地/远程一视同仁，远程搜的是远端工作区）。注：DSH 自带的「文件与文件夹」组只列本机文件，远程会话下请以「工作区文件」组为准。

**折叠（长对话救星，两层）**：① 单条折叠——任何很长的消息（你的输入或 kimi 的输出）会出现「折叠」小按钮（与消息同侧：输入在右、输出在左），折成七八行带渐变遮罩、点「展开」还原；折叠后被折的消息自动定位到屏幕中央，阅读位置不乱飘；折叠状态是阅读辅助，刷新不保留；② 全局「折叠步骤」开关——输入区工具行一键隐藏对话流里的所有 Think 行和工具调用行，再点恢复，状态记 localStorage。另外 DSH 自带的「轨迹」tab 有按轮折叠/全部折叠/时间线导航/搜索，三者互补。

**传文件（远程会话）**：远程会话的输入区工具行多一个「传文件 ⬆」按钮——后端直接 scp 到远程服务器的 `/tmp/frostfin-uploads`（目录可改）。文件两种选法：手输路径（每行一个），或点「浏览本机文件」开内置选择器（列主目录，点目录进入、点文件加入清单，文件按修改时间新的在前，还有「主目录/下载」快捷跳转）。大文件走本机直 scp 不经浏览器，几个 G 也扛得住。**带实时进度条**：每个文件先 scp 到远端临时名（`*.frostfin-part-*`），后端每 2 秒 stat 一次临时文件的字节数折算百分比（比 scp 终端进度条还准，且任何平台一致），到位后 mv 原子落成最终名，失败自动清半截文件。传输中按钮显示百分比，下拉里还有文件序号与已传/总字节。传完点「复制路径」把所有远端路径拷进剪贴板，粘进输入框补半句指令（"读一下这几个文件"）即可——kimi 看到路径会自己用工具去读（等价 kimi TUI 的 `@`，文件内容不进 prompt）。

## 会话生命周期与数据文件

- **DSH 重启**：会话从持久化日志恢复；kimi 进程在下一次 prompt 时自动重连（远程复挂活 pane，本地重 spawn + 回放）。
- **kimi 进程崩溃**：当前轮记错误，下一条消息自动重连继续。
- **我们的数据文件**（全在 `~/.frostfin/`）：
  - `kimi-sessions.json`：DSH↔kimi 会话绑定（含远程主机）；
  - `kimi-session-prefs.json`：每会话的模式/thinking 档位（重连重放用）；
  - `model-catalog.json`：模型目录缓存。
- **远程留下的东西**（服务器上）：tmux 会话（`frostfin-*`）和 `/tmp/frostfin-*` 的 fifo 文件——fifo 随系统重启消散；tmux 会话想收就 `tmux kill-session -t <名字>`。

## 升级与卸载

```sh
# 升级（dsh plugin 的参数原样转发给 pnpm——add dsh-frostfin@latest 或 @版本号 也行）
npx @deepseek-ai/dsh plugin --profile web update dsh-frostfin

# 卸载
npx @deepseek-ai/dsh plugin --profile web remove dsh-frostfin
```

升级后重启 `dsh web` 生效。卸载自动撤销一切注册，并把同步进 kimi `config.toml` 的托管块摘除（你的 kimi 配置原样恢复）。`~/.frostfin/` 下的绑定与缓存**刻意保留**以便重装续聊；彻底清除再 `rm -rf ~/.frostfin`。远程服务器上的 tmux 会话如需清理见上一节。

## 常见问题（FAQ）

**「月芒霜鳍鲸」的入口在哪？**
会话页面顶部，「对话」「轨迹」旁边的第三个 tab。

**为什么命令列表里找不到 `/plan`？**
`/plan` 是 DSH plan-mode 在 standard 等 preset 组合里注册的，frostfin 会话刻意不含它（它对 kimi 无效）。kimi 的 plan 用 `/frostfin-plan`。

**怎么调 thinking/effort？**
`/frostfin-thinking [档位]`：无参可查当前与可选档位，带参直接切换。可选档位集合以 kimi 当前模型上报的为准（off/low/medium/high/max 都可能出现，不支持的模型会明说）。

**后台任务在哪看？**
敲 `/tasks`（kimi 内建命令透传）列出任务与状态。常驻实时列表要等 kimi ACP 上游暴露任务状态。

**AgentSwarm 的子代理过程为什么看不到？**
kimi 的 ACP 适配器当前会过滤掉子代理事件（只发父调用卡片）。功能本身正常，嵌套展示等上游。

**工具卡片的入参显示 {}？**
曾是已知问题（kimi 流式生成工具参数时先发空创建、后补发完整入参，早期版本只读首次快照），已修复：补发到达时才落卡，入参完整显示。注意旧会话里修复前已落盘的空卡片不会回补。

**远程连接失败报错看不懂？**
体检会给出具体失败点（认证/tmux/kimi）；若报"kimi 拒绝了握手"，到那台服务器上跑一次 `kimi` 确认登录态。