DeepSeek GUI：把终端里的 AI Agent 搬进桌面工作台
DeepSeek TUI 能做的事情不少，但长期待在终端里用起来不轻松——多个项目要开多个窗口，变更审查靠 git diff，IM 接入要自己配脚本。DeepSeek GUI 把这些流程整合成一个图形化桌面应用，320 个 star，2026 年 5 月上线，本文拆解它的三种工作模式和 Write 模式里最值得看的技术实现。
定位：不是又一个聊天壳
项目 README 的第一句话说清楚了它想做什么：
这个项目的目标不是再造一个聊天壳，而是让 DeepSeek 变成一个可以稳定参与真实项目工作的桌面伙伴。
底层运行时是 DeepSeek TUI，GUI 层做的是把终端里的 agent 体验整理成：选目录、发任务、看推理过程和文件改动、审批或回退。设置、会话状态、日志都保存在本地，模型调用走用户自己的 DeepSeek API Key。技术栈：Electron + TypeScript。提供 macOS .dmg/.zip（Intel 和 Apple Silicon）和 Windows .exe，Linux 从源码构建。
三种工作模式
左侧顶栏切换：Code、Write、Claw。三种模式共享同一套 DeepSeek 运行时和设置，会话、工作区和界面布局彼此独立。
Code 模式
绑定本地项目目录，围绕代码仓库读写文件、执行命令。核心功能：
多工作区会话管理，按项目目录组织多个 agent 会话，实时看到推理过程、工具调用与文件变更。变更审查，内联 diff 和侧边审查面板记录 agent 产生的每一处文件改动，支持在应用内完成 review，不用跳出去开终端。
权限可控，支持只读、工作区可写、完全访问三个层级，并可以配置工具调用前是否需要人工审批。在不确定 agent 行为的阶段，可以让所有工具调用先暂停等待确认，确认后才执行。快捷任务卡片，预设了结构梳理、排错、实现方案、UI 优化等常用对话模板，一键发起。
Write 模式
独立的 Markdown 写作工作台，把写作文件、保存状态和 AI 助手从 Code 会话里拆出来单独管理，有自己的 ~/.deepseekgui/write_workspace。
编辑器支持 Live / Source / Split / Preview 四种视图，Live 模式在当前行保留 Markdown 源码，其余行实时渲染标题、任务项、图片、分割线和表格——参考了 openhanako 的 CodeMirror decorations 思路。
右侧写作助手提供摘要、大纲、润色等快捷操作；选中文本后可以唤起 inline agent，直接输入"润色/续写/分析"等指令，文件路径、行号和原文会作为结构化引用传给写作助手。
文档导出支持 HTML / PDF / DOC / DOCX，尽量保留标题、列表、代码块、表格和本地图片。
Write 模式最值得拆的是文本补全，下面单独展开。
Claw 模式
后台自动化与 IM 接入。可以为飞书 / Lark 配置独立 agent，分别设定人设、默认模型和工作目录，每个 agent 有独立会话线程，可以在 GUI 内直接调试回复和工具调用。支持本地 webhook/relay 和定时任务，适合把 DeepSeek 接到团队协作流程里。
Write 模式的文本补全：双模式设计
Write 模式里有一套精心设计的 ghost text 补全，把单一补全路径拆成了两种写作意图：短补全（short）和灵感长补全（long）。
为什么要拆
写作补全有两个互相冲突的目标：心流输入时要低延迟、短、准、不打扰；停顿思考时需要更完整的下一句或下一段，帮助接住灵感。用一套策略要么打断输入节奏，要么只给一两个词没有启发价值。
短补全
面向心流输入，触发条件相对宽松：光标不在选区内、光标后不是单词字符、文档有足够上下文、不在 URL 尾部。
关键参数：debounce 650ms，最大生成 96 个 token，ghost text 最多 6 行，最多注入 3 个 RAG 检索片段。候选显示阈值 0.52，过滤策略严格：惩罚过长候选、与 suffix 重复的候选、在完整句子后硬接词的候选、过于泛化的开头。目的是让短补全更像"下一串键入"，而不是 AI 主动写作。
灵感长补全
在短补全基础条件上额外要求：光标必须在行尾、当前行后没有剩余文本、不在表格或标题上下文中、当前行以单词字符结束时需要更长的局部信号量——这些限制确保长补全只在"用户真的停住了"的地方出现。
关键参数：debounce 2800ms，最大 256 个 token，ghost text 最多 14 行，最多注入 5 个 RAG 检索片段。候选显示阈值放宽到 0.36。
Prompt 会在前面加一段隐藏 Markdown comment，告诉模型用户是停顿寻求灵感，可以给更完整的下一句或下一段，但不要总结文档、不要生成整篇文章。
双计时器调度
编辑器插件内部维护 shortTimer 和 longTimer 两个计时器。每次文档、选区或焦点变化时，两个 timer 都会被清掉并重新设置。请求返回时会检查 sequence ID 和编辑器 state 是否仍然匹配，如果用户已经继续输入，旧请求会自然失效，不会把过期补全插入界面。
补全调用走 DeepSeek FIM /completions 接口，不走 chat completions——低延迟，直接。
Write 模式的跨文本检索（BM25 RAG）
补全还有一层：在请求 FIM 之前，从当前写作空间里检索相关片段，帮助模型保持术语、事实和风格连续性。
设计约束写得很清楚：不依赖 embedding、向量数据库或外部服务，只在主进程内存里跑，失败可以静默降级。
索引策略
扫描当前写作空间里的 .md、.markdown、.mdx、.txt 文件，跳过 .git、node_modules、dist 等目录。硬上限：最多扫 8000 个条目、索引 160 个文件、720 个块，单文件最大读取 600KB。
分块以 Markdown 结构为优先：标题行更新当前块标题，空行后的自然段可以形成边界，单块最大约 900 字符，过短片段丢弃。这样检索结果通常落在"一个自然段"上，而不是任意字符窗口。
分词与排序
同时支持中英文：英文提取长度 ≥ 2 的 a-z0-9_- token，中文生成 2~4 字 n-gram，过滤英文停用词，NFKC normalize 后转小写。
最终分数：
score = BM25(chunk, query) + keywordBoost(chunk, query)
查询由当前行（权重 3.0）、上一条非空行（2.0）、上一行（1.4）、文档尾部摘要（1.0）和更宽的局部上下文（0.7）组合而成，最多保留 36 个高权重 token。关键词增强对命中标题、文件路径、当前行短语额外加分。
注入方式
检索片段不追加到用户正文，而是以隐藏 Markdown comment 的形式放在 FIM prompt 前：
<!-- DeepSeek GUI inline completion references.
Use these snippets only for local terminology, factual continuity, and style. Do not insert or mention this comment.
Completion mode: short.
Retrieval: bm25-keyword; indexed 12 files / 38 chunks.
...
-->
原始 prefix...
对模型明确说明这些是 reference-only，不改变光标后的 suffix，模型返回结果只应该是可插入文本。
缓存
索引是 30 秒 TTL 的内存缓存，key 是写作空间根目录。写作时连续触发多次补全，不会每次都重新扫描文件；用户修改文件后 30 秒内可以刷新。
安装
从 GitHub Releases 下载：macOS .dmg/.zip（Intel / Apple Silicon），Windows .exe。
首次启动需要填写 DeepSeek API Key，如果使用兼容 OpenAI 格式的服务，可以在设置里修改 Base URL。
从源码运行：
git clone https://github.com/XingYu-Zhong/DeepSeek-GUI.git
cd DeepSeek-GUI
npm install
npm run dev
需要 Node.js 20+。国内访问慢可以加 --registry=https://registry.npmmirror.com。
本地数据存在 ~/Library/Application Support/DeepSeek GUI（macOS）、%APPDATA%\DeepSeek GUI（Windows）、~/.config/DeepSeek GUI（Linux）。卸载默认保留本地数据，彻底清理需手动删除。
适合谁用
README 里列了四类用户，实际来看最核心的两个场景：
想用 DeepSeek 处理真实代码库但不想一直留在终端里的开发者——Code 模式的变更审查和权限控制解决的是这个；需要长期写作、希望 AI 补全能理解写作空间里其他文档内容的人——Write 模式的双模式补全加 BM25 RAG 解决的是这个。
Claw 的飞书集成面向的是有团队协作需求、想把 DeepSeek 接进 IM 工作流的用户。
小结
三种模式各自独立又共享底座。Write 模式里双模式补全加跨文本检索的设计最值得看——不用向量数据库，纯内存 BM25，30 秒 TTL，失败静默降级，满足桌面本地应用的约束。代码库以 TypeScript 写成，贡献流程走 develop 分支，PR 前要过 typecheck + build + test。
