gjnzsu/dsh-companion

Install

DSH 负责维护事件日志和 projections。Companion 从 Web 客户端已经提供的当前 session summary 开始工作，不扫描事件日志，不轮询后端，也不重新实现上游统计逻辑。

更详细的设计资料：

- [产品设计](./docs/product/product-design.md)
- [视觉设计](./docs/product/visual-design.md)
- [架构设计](./docs/architecture.md)
- [MVP 用户故事](./docs/product/2026-08-16-mvp-user-stories.md)

## 状态说明

### 活动状态

| 状态 | 含义 |
| --- | --- |
| Sleeping | 当前还没有选中的 session |
| Idle | 当前 session 已准备好，没有正在执行 |
| Working | Agent 正在执行任务 |
| Waiting | Agent 正在等待问题、审批或其他用户交互 |
| Celebration / Done | 同一个 session 从 Working 进入 Idle 后的短暂完成反馈 |

`Waiting` 的优先级高于 `Working`，因为需要用户响应通常是更重要的信息。

### 上下文压力

| 等级 | 预计占用率 | 含义 |
| --- | ---: | --- |
| Unknown | 无法可靠计算 | projection 缺失或数据无效 |
| Normal | `< 70%` | 暂时不需要处理 |
| Attention | `70% – < 85%` | 上下文正在增长，值得留意 |
| Warning | `≥ 85%` | 可以考虑完成任务、压缩上下文或创建新 session |

压力等级同时使用文字、环形粗细和颜色表达，不依赖颜色作为唯一提示。

## 交互方式

- **悬停或键盘聚焦**：临时查看用量。
- **点击宠物**：固定或取消固定用量面板。
- **Escape 或点击外部**：关闭已固定面板。
- **拖动**：移动宠物；位置会保存在当前浏览器中。
- **折叠**：缩成最接近屏幕边缘的 `Show DSH Companion` 标签。
- **恢复**：点击边缘标签回到保存位置。

外层 overlay 是 click-through 的，只有宠物、面板和恢复标签接收指针输入。

## 用量指标

| 指标 | 定义 |
| --- | --- |
| Context | 预计 token 数除以模型 context window |
| Billed input | uncached input + cache read + cache write |
| Output | 供应商已报告并累计的 output token 数 |
| Cache hit | cache read ÷ billed input，四舍五入为整数百分比 |
| Steps | 已完成的 session steps |

不可用的指标会被省略，而不是被估算。

## 安装

从 npm 安装到 DSH Web profile：

Add gjnzsu/dsh-companion to your DSH config (web profile) to enable.