dsh-code

一句话定位

dsh-code 是 DeepSeek Harness (dsh) 的终端编码界面，把 Agent、会话、模型和工具搬到命令行里，让你在终端里就能开新会话、跑代码、改文件、做 diff 审查。它作为树外 bundle 挂在官方 @deepseek-ai/dsh-base 之上，运行时和 Web UI 共用同一套 Cordis 注册表。

核心能力

• 启动交互式 TUI，支持 dsh --profile cli、deepseek、dsh-code 三种入口命令（README.md:45-49 / bin/deepseek.mjs:197）
• 新建、续接、按 ID 前缀恢复、分叉持久会话；会话事件记录可在终端重放（src/index.ts:255-285 / README.md:62-67）
• 通过 Agent Preset（standard / code / minimal / cordis / 用户自定义）组合工具、技能、plan mode 和 subagent 行为，预设选择会随会话持久化（src/presets.ts:33-46 / README.md:78-79）
• 在终端内切换模型、reasoning effort、权限 Preset 和 subagent 模型路由，并把每次选择写为全局默认（src/index.ts:956-994 / src/index.ts:529-541）
• 提供 /diff、/review 工作流，结合 git 检查改动与只读代码审查；/export 把对话导出为 Markdown（README.md:104-108 / src/index.ts:1017-1040）
• 持久保存状态栏项目、主题（dark/light/auto）和输入历史到 ~/.dsh/dsh-code/ 下的 JSON/JSONL 文件（src/index.ts:555-628）

技术实现

• 语言: TypeScript
• 关键依赖: ink (^5.2.1)、react (^18.3.1)、commander (^14.0.2)、@deepseek-ai/dsh-agent (^0.1.0-rc.8)
• 架构模式: Cordis 插件树；以 bundle patch（cordis.patch.yml）挂载到宿主；启动时声明 tui-startup 服务，tui-runner 在 ctx.tuiStartup.startup 注入下懒加载会话
• 入口文件: src/index.ts（runner）、src/startup.ts（命令行解析）、bin/deepseek.mjs（launcher wrapper）

适用场景

适合习惯在终端里完成编码工作的开发者：想直接在命令行里跑 AI 编程会话，不想切到 Web；需要复用持久会话做长任务（恢复、分叉、跨目录续接）；要在 CI 或 SSH 远程环境里调用同一个 dsh 能力栈，而不是开浏览器。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:UNLINEARITY/dsh-code

配置项

常见问题

Q: 启动后报 the cli profile does not mount dsh-code yet 怎么办？

A: 意味着 alias 在的、但 profile 没挂上插件。执行 dsh plugin --profile cli add dsh-code（或带版本号 [email protected]）挂上，再用同样命令启动即可（bin/deepseek.mjs:170-179）。

Q: 用 GitHub 源码安装时 pnpm 反复提示 allowBuilds？

A: Git 包不含发布版的 lib/，会在 prepare 阶段构建；需要把 pnpm 提示里的完整条目（含 git URL 和 commit）原样写入 ~/.dsh/profiles/cli/pnpm-workspace.yaml，再重跑安装命令（docs/problems.md:60-99）。

Q: Linux 上报 Cannot find module './prebuilds/linux-x64/pty.node'？

A: 这是 DSH 主程序依赖的 [email protected] 缺预构建二进制。先 apt install build-essential python3 make g++，再 cd "$(npm root -g)/@deepseek-ai/dsh/node_modules/node-pty" 下执行 npx node-gyp rebuild，确认 build/Release/pty.node 已生成（docs/problems.md:5-58）。

Q: 模型切换后子代理（subagent）还在用旧模型？

A: 正常。子代理在创建时就已经确定 AgentOptions，运行时改 /model 不会回灌到子任务；可以用 /subagent 单独指定子代理模型，覆盖默认行为（src/index.ts:529-541 / README.md:81）。

Q: 怎么彻底卸载？

A: 需要两条都做：dsh plugin --profile cli remove dsh-code 解除挂载、npm uninstall -g dsh-code 移除全局包和 deepseek/dsh-code 命令。只解挂载时 alias 仍存在并报错提示（README.md:255-260）。

Q: 切换 Preset 报 mode is locked after the first turn？

A: 这是设计行为：首次 turn 之后 Preset 写进会话事件并锁定。要换 Preset 只能 /new <mode> 开新会话（src/presets.ts:60-72）。

Q: TUI 卡死或想中断当前 turn 怎么办？

A: Esc 中断当前 turn；Ctrl+C 依次用于取消任务、清空输入、退出；Ctrl+D 直接退出 DSH-Code。退出时 TUI 会按顺序 flush 会话、dispose agent、等待最后一次组合、写入历史再请求退出（README.md:181-188 / src/index.ts:647-682）。

上手难度

进阶 — 需要熟悉 Cordis 插件模型、DSH 持久会话事件流以及 pnpm 工作区机制才能理解 bundle patch 是怎么挂上去的；普通用户直接 dsh --profile cli 用即可。

已知问题与限制

• DeepSeek Harness 仍处于 developer preview（0.1.0-rc.8），后续可能有不兼容变更；dsh-code 1.0.x 是基于 rc.8 插件线构建，需保持全局 dsh 与 dsh-code 版本一致（README.md:54 / package.json:73-100）
• Linux x64 + Node 24 等无预构建二进制的环境下，[email protected] 全局安装可能留下缺失的 pty.node，需手动 node-gyp rebuild（docs/problems.md:5-58）
• 通过 --session <id> 自定义 id 创建会话时，回退到持久后端的 SQLite 等无 locatable artifact 时 /delete 会拒绝删除（src/index.ts:1098-1125）
• 续接子代理会话会被拒绝（subagent conversations are read-only），CLI 不能给子任务的持久日志追加根 turn（src/index.ts:276-279）
• pnpm 在包发布首 24 小时内忽略未固定版本的包，GitHub 安装首日需用精确版本 [email protected]；npm 安装不受此限（README.md:38-39）

English | 中文

---

一、项目概览

DSH-Code 是 DeepSeek Harness（dsh）的终端编码界面。 它以树外 bundle 的形式组合在官方 @deepseek-ai/dsh-base 之上，与 Harness Web UI 使用同一套 Agent、Session、工具、命令、技能、权限、sandbox、上下文压缩与插件服务。

DeepSeek Harness 将模型、工具、存储、策略和界面作为插件，通过 Cordis 注册。持久化会话事件记录恢复对话与运行状态所需的信息。DSH-Code 保留这套结构，并补充适合编码任务的终端工作流。界面采用开发者熟悉的终端操作方式，运行行为仍由 DSH 服务和配置决定。

二、快速开始

需要 Node ^22.19 || >=24 和预览版 dsh CLI（当前版本线：@deepseek-ai/[email protected]）。未配置模型时仍可进入 TUI、查看会话和使用非模型功能；在 /model 中按 a 可通过 Harness credentials 服务添加 API key。

1. 安装与更新

初次安装和更新使用同一组指令：

npm install -g @deepseek-ai/[email protected] [email protected]
npm install -g pnpm
dsh plugin --profile cli add [email protected]

提示：pnpm 会忽略发布不足 24 小时的包，因此发布首日请使用精确版本 [email protected]；24 小时后可省略版本号。npm 安装不受此限制。

版本对齐：dsh-code 1.0.x 基于 dsh 0.1.0-rc.8 插件线构建（peer 依赖全部为 ^0.1.0-rc.8），请保持全局 dsh 与 dsh-code 在同一版本线，避免宿主与插件版本不一致。

2. 启动指令

可用的启动指令：

dsh --profile cli
deepseek
dsh-code

dsh --profile cli、deepseek 与 dsh-code 是并列的启动命令。deepseek 与 dsh-code 都是 dsh --profile cli 的全局别名，后续参数会原样转发，例如 deepseek --resume abc123。

DeepSeek Harness 目前仍处于 developer preview，可能出现破坏兼容性的变化；DSH-Code 会持续跟随其插件接口演进。

安装、原生模块和插件加载问题，请查看常见问题与排障。

三、核心功能与使用方式

DSH-Code 的重点是让 DSH 的 Agent、模型、工具和持久会话可以直接在终端中使用，并覆盖从编写代码到审查修改的完整工作流。

1. 会话管理

• 使用 /new 新建会话，或通过 /resume、--continue 恢复已有会话
• 使用 /fork 从历史节点创建新的工作分支，同时保留原会话
• 按当前目录、更新时间和会话范围搜索历史记录
• 使用 Up/Down 召回输入历史，或通过 /history 搜索过去的提示词
• 支持持久标题、Markdown 导出、上下文占用、token、缓存、TTFT 和耗时统计
• 恢复会话时同步恢复该会话使用的 Agent Preset 和模型选择

2. Agent、模型与扩展

• 每个会话可以选择独立的 Agent Preset，用于组合工具、提示词、技能、上下文压缩、plan mode 和 subagent 能力
• 使用 /mode 选择 standard、code、minimal、cordis 或用户自定义 Preset
• 使用 /model 切换模型，并管理 provider、API key、endpoint、可用模型和上下文窗口
• 自动加载 DSH 中可用的命令与技能；使用 /help 查看入口，使用 /plugin 检查扩展状态
• 支持 plan、goal、todo、权限、sandbox、subagent 和运行中的补充指令

3. 模型切换动画

模型或 reasoning effort 发生以下变化时，输入框会播放 Wave、Aurora 或 Pulse：

高于 high 的等级包括 xhigh、x-high、very-high、max、maximum 和 ultra；high、medium、low 与 off 不会为非 DeepSeek 模型触发动画。

4. 编码工作流

• 使用 @ 引用工作区文件或已有会话，为任务补充上下文
• 支持启动 prompt 和多个 --image 图片输入
• 使用 /diff 按文件检查改动，使用 /review 发起只读代码审查
• 使用 /copy 复制最近一条完整回复，使用 Ctrl+O 查看完整历史和工具详情
• 支持工具审批、结构化提问、plan review、多选和自定义答案
• 使用权限 Preset 和 sandbox 控制 Agent 可以执行的操作；任务运行中仍可补充指令或中断

5. 命令与快捷键

启动 TUI：

dsh --profile cli                    # 新建 standard 会话
dsh --profile cli --mode code        # 使用指定 Agent Preset 启动
dsh --profile cli --continue         # 恢复当前目录最新会话
dsh --profile cli --resume abc123    # 按 id 或唯一前缀恢复会话
dsh --profile cli --session my-id    # 使用指定 id 新建会话

进入 TUI 后，可以使用以下内置命令。当前 profile 提供的其他 Harness 命令和用户技能会随安装内容变化，完整列表以 /help 显示为准。

会话与记录

Agent、模型与权限

编码、任务与后台工作

扩展、显示与退出

输入与快捷键

四、DSH-Code 如何接入 DSH

1. 运行时组合

DSH-Code 读取 Harness 的实时注册表，不在本地维护另一套副本。模型适配器、工具 provider、技能来源、命令、权限策略、持久化后端、sandbox 和 subagent provider 都可以通过 DSH composition 添加或替换。

/plugin 提供当前 Cordis loader 状态的只读视图。

2. 会话级 Agent Preset

Host 持有共享基础设施——注册表、持久化、会话查询、权限和 sandbox 策略；每个会话则获得一个隔离的 Agent scope，并由 Agent Preset 进行组合：

• standard——功能完整的通用编码 Agent
• code——面向 Code Mode / PTC 的多操作工作流
• minimal——只保留持久 shell 和 str_replace_editor
• cordis——完整 Agent，加上运行时检查与 Preset 编写指导
• 用户预设——自行定义工具、提示词段落、技能、上下文压缩、plan mode 与 subagent 行为

在第一次 turn 之前使用 /mode，或通过 --mode <preset> 直接启动。选中的 preset 会写入会话，并在恢复时还原。

3. 会话记录与恢复

提示词、流式 chunk、工具调用与结果、模型选择、plan 状态、权限、标题和 preset 选择都由持久 Session 事件投影得到。会话恢复、导出、历史检查、上下文统计和终端重放使用同一份记录。

React state 只保存输入草稿、光标、当前面板、选中项和滚动位置等临时界面状态。

dsh profile
└─ Host plane：注册表 · 持久化 · 查询 · 权限 · sandbox
   ├─ Agent 会话 A + preset code
   ├─ Agent 会话 B + preset minimal
   └─ DSH-Code TUI
      持久事件 → 纯投影 → 只追加的历史转录
                         └→ 有界面板 → 输入框 → 状态栏

五、开发

pnpm install
pnpm test
pnpm typecheck
pnpm build
pnpm run gen:whale   # 从 vendored Logo 路径重新生成 src/whale-glyph.ts

鲸鱼字形由 scripts/fish-logo.ts 中 vendored 的 DeepSeek FishLogo 几何数据生成（来源：DeepSeek Harness，MIT）。

1. 源码开发安装

本地 checkout 可使用：

dsh plugin --profile cli add file:C:/path/to/dsh-code

GitHub 安装可用于源码开发：

dsh plugin --profile cli add github:unlinearity/dsh-code

Git 包会在安装阶段构建。若 pnpm 要求添加 allowBuilds，请把它输出的完整条目复制到 ~/.dsh/profiles/cli/pnpm-workspace.yaml，再重新执行命令。该键包含 Git URL 与 commit，不能只写 dsh-code。

2. 卸载

dsh plugin --profile cli remove dsh-code   # 移除 cli profile 中的插件挂载
npm uninstall -g dsh-code                  # 移除全局包与 deepseek / dsh-code 命令

两条都要执行才是全量卸载：第一条只解除 profile 挂载，此时 deepseek 命令仍存在并提示 "the cli profile does not mount dsh-code yet"；第二条移除全局 npm 包与启动别名。卸载不影响 @deepseek-ai/dsh 本体与已持久化的会话数据。

3. 参考

• 运行时服务、事件、插件作用域和持久化模型遵循 DeepSeek Harness。
• 会话导航、浮层尺寸、scrollback、底部布局与缩放处理参考 Codex CLI。
• 斜杠发现、turn steering、思考折叠、审批和提问流程参考 Claude Code。

DSH-Code 是独立的 MIT 社区项目，与 OpenAI 或 Anthropic 无隶属关系。

社区：

• Linux DO：学 AI，上 L 站！
• Deepseek harness: DSH 官方网站

许可

MIT。vendored FishLogo 几何数据来自 DeepSeek Harness（MIT）。