# dsh-phosphor

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的第三方全屏 Matrix 风 TUI 前端——以 Cordis bundle 插件形态实现，React + Ink 构建。

[English README](README.md)

```
█▓▒ PHOSPHOR ▒▓█
```

![matrix 主题](docs/screenshots/matrix.png)
![terminal 主题](docs/screenshots/terminal.png)

## 现状：仅源码分发（暂时）

**dsh 处于 developer preview，官方明示存在兼容性破坏变更。** 本插件与宿主内部插件 API 深度耦合——宿主一次升级就可能让插件无声坏掉（我们亲历过）。此刻发布 npm 包或 tarball 是在伪装稳定：没有更新通道、没有版本护栏，下一个宿主 rc 之后你只会得到一个坏掉的 TUI。

因此，在 dsh 发布稳定版之前：

- **仅源码**：你需要自行 clone、构建，并 link 到你自己的 dsh 源码 checkout——这会强制你清楚地知道自己跑的是哪个宿主版本。
- **锁定基线：dsh `v0.1.1-rc.2`**（commit `b150a551b8`）。其他版本或许能跑，但未测试。
- **不支持 `dsh plugin add github:...`**：pnpm 会在自己的缓存目录里运行 `prepare`，本仓库的 `link:` devDependencies 在那里无法解析。请走下方的源码流程。
- 待 dsh 稳定后，我们会先对齐源码，再正式发布 npm 包。

## 环境要求

- Node.js `^22.19 || >=24`、pnpm
- 一个已构建的 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) **源码 checkout**（`pnpm install && pnpm run build`）
- 开发基准为 Windows Terminal；其他终端未经实测（见已知限制）

## 从源码安装

插件通过**相对路径 link** 解析 `@deepseek-ai/*` 开发依赖，因此两个仓库必须位于同一父目录下：

```
<工作区>/
├── deepseek-harness/     # dsh 源码 checkout（锁定基线）
└── dsh-phosphor/         # 本仓库
```

```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness && git checkout b150a551b8 && pnpm install && pnpm run build && cd ..

git clone https://github.com/yaotongsb/dsh-phosphor.git
cd dsh-phosphor && pnpm install && pnpm build

# 一次性注册进 profile（在 dsh 源码目录下执行，相对路径才能正确解析）：
cd ../deepseek-harness
pnpm dsh plugin --profile tui add ../dsh-phosphor
```

## 启动

dsh 以**启动目录为工作区根**——在你想工作的项目目录里启动即可。`pnpm dsh` 只存在于 dsh 源码仓库内；日常使用请从任意目录直接运行构建产物：

```sh
cd your-project
node /path/to/deepseek-harness/apps/cli/lib/bin.js --profile tui
```

建议配一个 alias 省去输入：

```sh
# ~/.bashrc
alias dsh-tui='node /path/to/deepseek-harness/apps/cli/lib/bin.js --profile tui'
```

每次改动插件代码后在本仓库 `pnpm build` 即可——profile 以 link 指向本目录，下次启动自动加载新的 `lib/`。

## 命令

phosphor 自有命令：

| 命令 | 说明 |
|---|---|
| `/help` | 命令帮助 |
| `/model` | 模型选择——输入过滤，`Shift+Tab` 循环 reasoning effort |
| `/new` | 新建会话（`Ctrl+N`） |
| `/resume` | 会话切换——输入过滤，`a` 归档高亮会话 |
| `/attach <路径>` | 附加图片到下一条消息（需图像模型；png/jpeg/webp/gif） |
| `/detach` | 清空待发送图片 |
| `/plugins` | 宿主插件清单（loader 反射：启用态、fiber 相位、生效配置） |
| `/settings` | 运行时设置面板（权限预设 + 视觉项） |
| `/theme matrix\|terminal` | 切换主题 |
| `/exit`、`/quit` | 退出 |

宿主（dsh-base）提供、经 phosphor UI 呈现的命令：

| 命令 | 说明 |
|---|---|
| `/compact` | 压缩会话历史 |
| `/plan` | plan 模式（全屏审阅弹层） |
| `/goal` | 设定/跟踪会话目标 |
| `/permission` | 权限设置 |
| `/feedback` | 提交反馈 |

## 键位

全局：

| 键 | 作用 |
|---|---|
| `Ctrl+C` | 退出 |
| `Ctrl+L` | 整屏重绘（清除任何幽灵帧） |
| `PgUp` / `PgDn` | 转录回看滚动 |

编辑器：

| 键 | 作用 |
|---|---|
| `Tab` / `↑` / `↓` | 斜杠命令提示导航 |
| `@` | 文件引用补全（模糊匹配，cwd 根） |
| `↑` `↓` `←` `→` `Home` `End` | 光标移动（多行感知） |
| `Ctrl+U` | 清当前行 |
| `Esc` | 取消 / 关闭浮层 |

输入缓冲区**为空**时：

| 键 | 作用 |
|---|---|
| `Alt+T` / `Alt+J` / `Alt+F` | 打开侧栏面板：TRACE / JOBS / FILES |
| `Alt+O` | 折叠/展开侧栏 |
| `Alt+1..9` | 跳转最近会话 |
| `Ctrl+N` | 新建会话 |
| `x` | 杀掉选中 job（JOBS 面板，`↑`/`↓` 选择） |

浮层：

| 场景 | 键位 |
|---|---|
| plan 审阅 | `↑↓` / `PgUp`/`PgDn` 滚动 · `y` 批准 · `n` 继续规划 · `o` 带反馈继续 · `Esc` 退出说话 |
| 审批栏 | `y` 批准 · `n` 拒绝 |
| 会话选择 | 输入过滤 · `a` 归档 · `Enter` 打开 |

## 配置

全部配置项经 Schemastery schema 校验，通过 cordis.yml 层叠设置——例如你的 profile 补丁 `~/.dsh/profiles/tui/cordis.patch.yml`：

```yaml
- id: phosphor
  config:
    theme: matrix
    matrixRainFps: 8
```

| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `theme` | `matrix \| terminal` | `matrix` | 配色方案 |
| `matrixRain` | boolean | `true` | 数字雨背景层 |
| `matrixRainFps` | 2–24 | `8` | 雨帧率上限（负载下自动降帧） |
| `scanlines` | boolean | `false` | CRT 扫描线覆层 |
| `panelWidth` | 16–48 | `26` | 侧栏宽度（列） |
| `panelMode` | `trace \| jobs \| files` | `trace` | 启动时的面板模式 |
| `showReasoning` | boolean | `false` | 默认展开推理块 |
| `showInjected` | boolean | `false` | 完整渲染注入上下文（AGENTS.md、hooks） |
| `verboseStatus` | boolean | `false` | 状态栏详细计数 |

视觉项的运行时开关在 `/settings` 里；配置文件负责持久化默认值。

## 主题

- **matrix**——黑底 + 三档霓虹绿、数字雨、呼吸状态点、可选扫描线。雨只从空白格透出，负载下自动减半帧率。
- **terminal**——沿用终端 16 色调色板；一切动画退化为静态。

## 已知限制

- **版本锁定** dsh `v0.1.1-rc.2`；在官方稳定版之前，宿主升级可能破坏功能。
- 终端不渲染图片本体——附件以 dim 占位行呈现（`▣ name (W×H)`）。
- plan 模式无常驻徽标（模式本身完整生效，只缺指示器）。
- 超长会话的 resume 较慢（宿主侧日志回放）；雨帧率随系统负载自适应属设计行为。
- V1 无取消归档；归档与 web UI 共享存储（`~/.dsh/storages`），多进程同时运行为 last-writer-wins。
- 仅在 Windows Terminal 上开发测试。

## 开发

```sh
pnpm install     # 需要同级目录的 deepseek-harness checkout
pnpm test        # vitest，426 个测试
pnpm typecheck   # tsc --noEmit
pnpm build       # tsdown → lib/
```

开发循环在 dsh 源码仓库执行：`pnpm dsh --profile tui`。

代码库小而分层（`bridge/` → `store/` → `ui/`，中间是纯函数转录投影），从 `src/index.ts` 与各模块旁的测试读起即可。欢迎再开发。

## License 与致谢

[MIT](LICENSE) © yaotongsb

markdown 渲染器（`src/ui/markdown.ts`：块结构、表格列宽算法、流式围栏修剪、行内基础样式回补）移植自 **PI**（`packages/tui/src/components/markdown.ts`）——MIT License, Copyright (c) 2025 Mario Zechner。