原生逆向智能体 Weeabo-Inc/dsh-rs

dsh-rs

dsh-rs：一张 run_code 卡片，带实时子调用和带类型的返回值、一处编辑 diff、一个待审批项、Subagents 停靠标签页，以及成本 / 缓存命中状态栏

所有截图都来自 GUI 的演示场景（cargo run -p dsh-gui --example demo），用的是假会话数据。截图使用可选的 orca-link 皮肤；其美术资源采用 CC BY-NC-SA 4.0 协议（见 Licensing）。

dsh-rs 是一款快速的原生智能体 harness，用 DeepSeek 做逆向工程。它是 DeepSeek Harness（TypeScript）的 Rust + Bevy 重写版，以单个桌面应用 dsh-rs 的形式发布。内置静态分析覆盖 PE、ELF、Mach-O、COFF 和 .NET 二进制，还带一座通往 Ghidra 反编译器的桥。有了程序化工具调用（run_code），模型写一段 TypeScript 程序，就能以一次模型往返的成本扇出到几十个工具。它没有插件系统、没有 Web UI、也没有服务器，应用不打开任何监听套接字。你要扩展它，就从外部来：用 MCP 服务器、Claude-Code 风格的命令钩子、技能和 AGENTS.md。

默认权限是 full-access，没有沙箱。 dsh-rs 是为在你自己的机器上分析二进制而造的。如果这不是你想要的，就选 ask 或 read-only（输入框、Settings → General，或 --permission）。

目录

- 亮点
- 安装与构建
- 设置 API key
- GUI 导览
- 逆向工程套件
- 程序化工具调用（run_code）
- 命令行参考
- 工具
- MCP 服务器与 Ghidra
- 钩子
- 技能
- AGENTS.md 与 CLAUDE.md
- 文件与存储位置
- 环境变量
- 性能
- 故障排查
- 开发
- 许可
- 架构 · 基准测试

亮点

智能体与 DeepSeek

- DeepSeek 优先。 dsh-rs 使用 DeepSeek 的 Anthropic 兼容端点，支持 thinking 和 reasoning effort（off / low / medium / high / max）。默认路由是 deepseek/deepseek-flash（V4.1-Flash：视觉、1M token 上下文）；deepseek-v4-pro 也已内置。Anthropic 以及任何 OpenAI 兼容端点（OpenRouter、Ollama、vLLM、LM Studio）都能作为服务商加入。
- 感知前缀缓存。 请求保持字节稳定的前缀（固定的系统提示词和 SDK 文本，追加式上下文），所以 DeepSeek 的自动 KV 缓存承担了大部分工作。
- 成本与缓存仪表盘。 状态栏显示上下文用量、会话的缓存命中占比、输入和输出 token，以及会话成本（美元）。成本按标价计算，包含 DeepSeek 的高峰与低谷（半价）时段。
- 通过 Files API 处理图片。 体积大或重复出现的图片只上传一次，之后用 file id 引用。上传按 SHA-256 去重；上传失败时，dsh-rs 回退到内联 base64。发送前会先校验文档中写明的限制。
- 长会话。 上下文压力过大或溢出时触发压缩。体积大的工具结果落盘。轮次运行中可以干预（steer），也可以排队（followup）。
- 子代理、目标与计划模式。 subagent（带 send_message、interrupt_agent 和 list_agents）、create_goal / update_goal、todos，以及用于评审计划的 exit_plan_mode。
- 工作流。 workflow 和 ralph 在 run_code 所用的同一个 JavaScript 运行时上跑脚本化的多智能体循环。

程序化工具调用。 run_code 会拿到一份生成的、带类型的 .d.ts SDK，覆盖所有可见工具（含 MCP 工具）。调用解析到每个工具的结构化值，而不是它的展示文本。每个程序的开销约 0.3 ms，每次子调用约 25–32 µs（详情）。

逆向工程（详情）

- 26 个进程内 dsh-re 工具：格式与文件头、节区、符号、字符串、反汇编、CFG 与跳转表、交叉引用、熵、加密常量、RTTI、.NET 元数据与 IL、差分、导出，以及带校验和修复的补丁。
- 内置 Ghidra 桥：ghidra 工具与 GhidraMCP 插件通信，获取反编译器输出、重命名、注释和原型。一键 MCP 模板覆盖 GhidraMCP、radare2、rizin、IDA Pro 和 Binary Ninja。
- 一套 RE 技能包，首次运行时安装：分类、字符串搜寻、Ghidra 工作流、PTC 配方、动态笔记和发现记录规范。
- 停靠栏里的发现笔记本（notes/findings.md）。你可以把任意消息或工具结果固定到里面。
- 二进制拖放。 在输入框里拖入或附加文件，会变成一个引用芯片，显示大小、识别出的格式和 SHA-256。字节内容绝不会粘贴进上下文。

桌面 GUI（导览）

- 用 Bevy 和 egui 做 GPU 渲染。窗口空闲时 CPU 占用为零，打开 127k 事件的会话只需毫秒级。
- 停靠栏标签页： Todos、Goal、Terminals、Jobs、Subagents、Files、Findings、Ledger、Inspector 和 Skin。
- 消息操作： 复制、编辑（作为分叉重新发送）、重试、固定到发现记录。会话操作： 搜索、重命名、分叉、导出（Markdown 或 zip）和删除。
- Ctrl+K 会话切换器、Ctrl+F 会话内查找，以及 F1 快捷键浮层。
- 轮次结束、或有审批/提问等待时，发送系统通知。
- 设置页面涵盖 Providers、General 和 RE integrations。
- 可选 皮肤，用来更换图片和配色（内置 orca-link 和 maid-atelier）。

集成接口。 dsh-rs run（无头模式，可输出 NDJSON）、dsh-rs sdk （JSON-RPC 2.0，兼容 DeepSeek Harness Python SDK）和 dsh-rs acp（Agent Client Protocol v1，供编辑器使用）。三者都走 stdio，作为调用方进程的子进程运行。

安装与构建

发布版 zip。 解压 dsh-rs-<version>-windows-x64.zip，运行 dsh-rs.exe。zip 里有二进制文件、可选的 skins/、LICENSE、THIRD_PARTY.md 和这份 README。想在终端里用 stdio 命令，就把该文件夹加进 PATH。

从源码构建。 需要 Rust 1.95 或更高版本。在 Windows 上，这意味着 MSVC 工具链加 Windows SDK；SDK 的资源编译器负责嵌入 exe 图标和清单。

git clone <this repository> dsh-rs && cd dsh-rs
cargo build --release -p dsh-cli # target/release/dsh-rs(.exe)
cargo run --release -p dsh-cli # open the GUI
cargo run --release -p dsh-cli -- run "describe samples/a.exe"

在 Linux 上，Bevy 需要 X11/Wayland 开发包（例如 libx11-dev libxkbcommon-dev libwayland-dev libudev-dev）。

| 配置档 | 用途 |
| dev | 日常开发（opt-level = 1；依赖用 opt-level = 2）。 |
| release | 本地快速构建：thin LTO，16 个 codegen unit。 |
| dist | 分发构建（cargo xtask dist）：fat LTO，1 个 codegen unit，已 strip。 |

设置 API key

给 dsh-rs 配 DeepSeek key 有三种方式：

1. Settings → Providers（GUI）。点齿轮图标或按 Ctrl+，选择 DeepSeek。粘贴 key，按 Save key。key 存在 <home>/credentials.yaml，之后 GUI 只显示最后 4 个字符。
2. 命令行： dsh-rs providers set-key deepseek。key 从隐藏提示符读取，管道输入时从 stdin 读取。绝不作为参数传入。--clear 删除已存的 key。
3. 环境变量： DEEPSEEK_API_KEY。

key 按以下顺序解析：

1. 服务商的环境变量；
2. <home>/credentials.yaml；
3. <cwd>/.env；
4. <home>/.env。

要检查服务商，运行 dsh-rs providers test deepseek，或在 Settings 页面按 Test。

其他服务商。 从 Settings 预设里添加 Anthropic、OpenAI 兼容端点或自定义端点，也可以用 dsh-rs providers add：

dsh-rs providers add ollama --kind openai-compatible --base-url http://localhost:11434/v1 --model qwen3-coder
dsh-rs providers default ollama/qwen3-coder

Settings → Providers: provider cards with key status and connection tests, and the DeepSeek editor

GUI 导览

运行 dsh-rs（或 dsh-rs gui）。选项：--cwd DIR、--theme dark|light 和 --font-size N。默认值来自 Settings → General（<home>/preferences.json）。每个 home 目录只能跑一个 GUI。第二次启动会把正在运行的窗口提到前台，然后退出。
- 左侧边栏： 会话列表和搜索框。+ New 在你选择的工作目录里新建会话。右键点击会话（或悬停其上）可以重命名、fork、导出为 Markdown 或 zip，或者删除。
- 聊天： 流式 Markdown（表格、本地图片、可点击的 path:line 引用）、可折叠的推理过程、审批提示、ask_user_question 对话框和工具卡片：
- run_code： 程序、实时显示的子调用列表及耗时，返回值以 JSON 树呈现；
- edit / write： 统一 diff；
- bash / pwsh： 终端输出；
- read： 带行号的内容（二进制文件显示十六进制）；read_image 显示图片；
- 其他所有情况： JSON 树。任意卡片上的 {} 开关可以查看原始 JSON。

悬停在消息上可以看到 Copy、Edit（作为 fork 重新发送）、Retry 和 Pin。工具卡片提供 Copy output、Copy args 和 Pin。
- 输入区： 模型、effort、权限预设（full-access / ask / read-only）、呈现方式（both / native / ptc）和提示词模式（followup / steer）的选择器。你可以用文件对话框、剪贴板或拖放来附加图片。斜杠命令有 /compact、/plan、/clear 和 /settings，@ 可以补全文件名。
- 状态栏： 智能体状态、模型和 effort、上下文用量、缓存命中占比、会话费用、输入和输出的 token 数、回合计时器和事件计数。
- 通知： 窗口在后台时，回合结束、等待审批或提问、出错都会变成系统通知。窗口在前台时，只显示其他会话的事件，以应用内 toast 呈现。你可以在 Settings → General 里关掉它。

附件。 图片会变成缩略图。其他任何文件，比如可执行文件、DLL 或固件镜像，会变成一个引用 chip，显示它的大小、从 magic bytes 检测出的格式和 SHA-256。模型收到路径和元数据，用自己的工具处理这个文件。

输入区，带两个图片缩略图和两个二进制引用 chip（PE32+ 可执行文件和 DLL）

右侧停靠栏。 标签页有：

| 标签页 | 内容 |
| Todos、Goal | 智能体的待办列表和当前目标。 |
| Terminals | 智能体或你打开的 PTY 终端（+ shell、+ pwsh、+ cmd），支持输入和 Ctrl+C。 |
| Jobs | 后台命令及其状态、退出码或信号、实时输出，以及 Kill。 |
| Subagents | 子代理树，带状态和结果摘要（见顶部截图）。 |
| Files | 工作区目录树（遵循 .gitignore），带打开和定位操作。 |
| Findings | notes/findings.md 笔记本：渲染、可编辑，也是 Pin 的目标。 |
| Ledger、Inspector | 每个记录的事件及其 token 和耗时详情，以及原始事件 JSON。 |
| Skin | 皮肤选择器和美术署名。 |

Findings，带一条固定笔记后台任务

PTY 终端 Ctrl+K 会话切换器

键盘快捷键（F1 在应用内显示）：

| 按键 | 操作 |
| Ctrl+N | 新建会话 |
| Ctrl+K | 切换会话（模糊搜索） |
| Ctrl+L | 聚焦消息框 |
| Esc | 取消正在运行的回合（消息框为空或未聚焦时） |
| Ctrl+, | 设置 |
| Ctrl+F | 在当前会话中查找（Enter / Shift+Enter：下一个 / 上一个） |
| Ctrl+Shift+C | 复制最后一条助手消息 |
| F1 或 Ctrl+/ | 显示快捷键 |
| Enter / Shift+Enter | 发送 / 换行 |

F1 快捷键浮层

设置。 设置页有三个标签页：

- Providers： 服务商、模型、密钥和连接测试（见上文）。
- General： 主题、字号、皮肤和通知，立即生效。这里还有新会话的默认值：权限、工具呈现、工作目录、时间上下文、并行工具调用、提前启动工具和溢出大小。
- RE integrations： Ghidra 桥接和 MCP 服务器（见下文）。

设置 → General

皮肤是可选的运行时目录，存放图片和颜色。不选皮肤时，使用内置的深色和浅色主题。你可以在顶栏、设置 → General 或 Skin 标签页里选皮肤。

orca-link，浅色 maid-atelier，空会话

逆向工程套件

dsh-re 工具默认注册；--no-re 会移除它们。它们在进程内解析 PE、ELF、Mach-O（包括 fat 二进制）和 COFF 对象。iced-x86 反汇编 x86 和 x64，capstone 处理 ARM、ARM64、MIPS、PowerPC 和 RISC-V。原始二进制块可以用字节级工具处理，给定 arch 后也能用反汇编器。每个工具都返回带输出模式的结构化值，所以 run_code 程序可以串联这些工具。

所有工具都只读，patch 和 sign_fixup 除外。它们只读取，不执行、不修改、不上传任何东西，并且并行运行。

| 类别 | 工具 | 作用 |
| 概览 | bin_info | 格式、架构、入口点、头信息、导入导出摘要。 |
| | analyze | 分类报告：按严重程度列出加壳、熵、异常和可疑特征。 |
| | archs | fat 或 universal 二进制中的各个切片。 |
| 布局 | sections | 节与段，含权限、大小和熵。 |
| | symbols | 符号、导入和导出（已还原修饰名），可过滤。 |
| | functions | 已知和已发现的函数，含大小。 |
| | relocs | 重定位。 |
| | va_convert | 在 VA、RVA 和文件偏移之间转换。 |
| 字节与字符串 | strings | ASCII 和 UTF-16 字符串，支持正则过滤，显示所在节和 VA。 |
| | search_bytes | 字节或模式搜索（支持通配符）。 |
| | hexdump | 以十六进制、字节或文本视图查看某个范围。 |
| | extract | 取出某个字节范围，输出为 hex、base64、u8 列表或文本。 |
| | entropy | 熵分布图、各节熵值和高熵区域。 |
| | signatures | 已知常量：加密原语（AES、SHA、CRC、ChaCha 等）以及压缩或归档魔数。 |
| 代码 | disasm | 从某个地址反汇编，标注调用和跳转目标（Intel 或 AT&T 语法）。 |
| | disasm_function | 单个函数及其 CFG：基本块、后继、尾调用和跳转表。 |
| | field | 解码任意位置的几个字节（vtable 槽或 thunk），列出它们引用的所有内容。 |
| | jump_tables | 还原 switch 跳转表。 |
| | xrefs | 与某个地址、符号、导入或字符串相关的交叉引用（调用、跳转、数据）。 |
| | data_refs | 匹配过滤条件的字符串，以及使用它们的指令和函数。 |
| 托管代码与 C++ | rtti | MSVC C++ RTTI：类型描述符、类层次结构和 vtable。 |
| | dotnet | .NET 元数据：类型、方法、IL 方法体。 |
| 比较与输出 | bin_diff | 比较两个二进制：节、符号、导入导出、头信息。 |
| | export | JSON 报告，或 AArch64 汇编清单。 |
| 写入 | patch | 按偏移或 VA 修改字节，支持 if_match 前置条件，并生成 .bak 副本。 |
| | sign_fixup | 打补丁后重新计算 PE 的 CheckSum 字段。 |
| Ghidra | ghidra | GhidraMCP 插件 REST 桥的客户端：反编译、列表、搜索、交叉引用、重命名、注释、设置原型和类型。 |

地址可以是数字、十六进制字符串、符号，或 symbol+0xoff。列表用 offset / limit 分页，并报告 total / next_offset。

RE 技能包。 首次运行时，会把六个技能安装到 <home>/skills。dsh-rs skills install [--force] 可重新安装。你删掉的技能不会再次安装。

| 技能 | 用途 |
| binary-triage | 初次查看未知二进制：摘要、假设、初步发现。 |
| string-hunting | 找出有意义的字符串，并映射到使用它们的代码。 |
| ghidra-workflow | 通过 Ghidra 桥或 Ghidra MCP 服务器反编译、导航和注释。 |
| ptc-recipes | 现成的 run_code 程序，用于批量检查。 |
| dynamic-notes | 在终端和作业里驱动调试器或 harness，记录运行时发生的事。 |
| findings-discipline | 把每条结论记进 notes/findings.md，附上地址、证据和状态。 |

Findings 笔记本。 会话目录里的 notes/findings.md 是共享的结果记录。它会在 Findings 标签页里显示、渲染，也可以编辑。在消息或工具卡片上点 Pin，就会追加一段片段，带上时间戳和指回会话的链接。

程序化工具调用（run_code）

默认的 both 呈现模式下，模型看到的是常规 JSON-schema 工具加上 run_code。run_code 接收 code（一个 async TypeScript 函数的函数体）和 description。oxc 剥掉类型，程序在嵌入式 QuickJS 运行时里跑。只有程序打印或返回的内容会回到模型的上下文里。

在程序内部：

- tools.<name>(args) 调用工具，解析为它的结构化值。值的类型由工具的输出 schema 决定；系统提示词里带一份生成的 .d.ts SDK，包含所有可见工具，MCP 工具也在内。
- ToolCallError 是调用失败时 reject 出来的东西。它带 toolName、code 和 message。
- 全局对象： console、setTimeout、TextEncoder / TextDecoder、atob / btoa，以及辅助函数 sleep、hex、parseHex 和 std.path、std.toHex / std.fromHex、std.utf8。
- 不可用： require、import、process、fs 或 fetch。每个副作用都走工具，所以审批、钩子和日志对每次子调用都生效。
- 并发： 独立的只读调用在 Promise.all 下并行跑（一次 10 个）。有副作用的调用单独跑，按顺序来。
- 限制： 每次运行 120 s，内存 512 MiB，合并输出 64 MiB，子调用 10,000 次。
- 速度： 启动程序并返回耗时 274 µs（剥 TypeScript 类型时 314 µs）。每次子调用增加 24 µs（并行）到 32 µs（串行）的调度开销。见 docs/benchmarks.md。

一个示例程序，模型会这样写：

// Which code references the licence-related strings in this binary?
const bin = "samples/crackme.exe";
const s = await tools.strings({ path: bin, filter: "licen[cs]e|serial|trial", unique: true, limit: 50 });
const hits = await Promise.all(
s.strings.filter((x) => x.va).map(async (x) => {
try {
const r = await tools.xrefs({ path: bin, target: x.va!, direction: "to" });
return { text: x.text, va: x.va, from: r.xrefs.map((x) => x.function ?? x.from) };
} catch (e) {
if (e instanceof ToolCallError) return { text: x.text, va: x.va, error: e.code };
throw e;
}
}),
);
console.log(${s.total} matching strings);
return hits.filter((h) => "from" in h && h.from.length > 0);

用 --presentation native 只提供 JSON-schema 工具，用 ptc 只提供 run_code。

命令行参考

Usage: dsh-rs [COMMAND]

Commands:
run 无头运行一个任务后退出（推理和工具调用输出到 stderr，答案输出到 stdout） sessions 列出、查看、导入或 fork 已存储的会话 models 列出每个已配置服务商的已知模型 providers 管理 LLM 服务商、API 密钥和默认模型（<home>/providers.json） skills 管理 <home>/skills 中内置的逆向工程技能 gui 打开桌面 GUI（不带命令时的默认行为） sdk 基于 stdio 的 JSON-RPC SDK 服务器（Python SDK） acp 基于 stdio 的 Agent Client Protocol（ACP v1）（供编辑器使用） help 打印这条消息，或指定子命令的帮助

| 命令 | 子命令与选项 |
| sessions | list、show、import（DeepSeek Harness v3/v4 日志）、fork（--at SEQ）、delete（-y 跳过确认）、export（--format md\|zip、-o FILE） |
| providers | list、add、remove、set-key（从 stdin 或隐藏提示读取；--clear）、test、default |
| skills | install（--force 覆盖已有文件） |
| models | --json：每行一个 JSON 对象 |
| gui | --cwd、--theme dark\|light、--font-size N |
| sdk | --dsh-events：以 dsh v4 JSON 输出会话事件（兼容 Python SDK） |
| acp | 为创建的会话指定 -m MODEL、--effort、--permission |

dsh-rs run [OPTIONS] <TASK>（- 表示从 stdin 读取任务）：

| 选项 | 含义 |
| -m, --model <MODEL> | model 或 provider/model（默认 deepseek/deepseek-flash） |
| --effort off\|low\|medium\|high\|max | 推理强度。 |
| --cwd <DIR> | 会话工作目录。 |
| --presentation native\|ptc\|both | 以何种方式向模型提供工具（默认取自 preferences.json，否则为 both）。 |
| --permission full-access\|ask\|read-only | 权限预设（默认取自 preferences.json，否则为 full-access；在无头模式下，ask 会拒绝有副作用的调用）。 |
| --json | 把每个客户端事件以 NDJSON 输出到 stdout。 |
| --image <PATH> | 附加 PNG、JPEG、GIF 或 WebP 图片（可重复）。 |
| --timeout <SECS> | 超过这么多秒后放弃。 |
| --no-mcp、--no-hooks | 跳过 MCP 服务器或命令钩子。 |
| --no-re | 不注册逆向工程工具。 |
| --ghidra、--ghidra-url <URL> | 注册 ghidra 工具（默认 URL 为 $DSH_GHIDRA_URL 或 http://127.0.0.1:8080）。 |
sh
dsh-rs run --cwd samples "Triage crackme.exe: format, imports, suspicious strings, entry point"
git diff | dsh-rs run --permission read-only -
dsh-rs run --json -m deepseek/deepseek-v4-pro "..." > events.ndjson

退出码：

| 退出码 | 含义 |
| 0 | 本轮已完成。 |
| 1 | 出错。 |
| 2 | 达到 max-tokens 上限而停止。 |
| 3 | 被拦截，例如被钩子拦截。 |
| 101 | 内部错误（panic；会写出崩溃报告）。 |
| 130 | 已取消。 |

第一次按 Ctrl-C 取消本轮；再按一次 Ctrl-C 退出。

工具

| 分组 | 工具 |
| 文件 | read、read_image、write、edit、glob、grep、list_dir |
| Shell | bash、pwsh；后台任务 job_output、job_list、job_kill；PTY 终端 terminal_open、terminal_send、terminal_read、terminal_signal、terminal_list、terminal_close |
| Agent | todo_write、ask_user_question、exit_plan_mode、create_goal / get_goal / update_goal、subagent、send_message、interrupt_agent、list_agents、session_event_read、session_event_search、run_code、workflow、ralph |
| Web | web_fetch、web_search（默认用 DeepSeek；DSH_WEB_SEARCH_BACKEND=brave\|exa） |
| Extensions | skill（存在技能时）、lsp（<home>/lsp.json 列出服务器时）、mcp__<server>__<tool> 以及 MCP 资源工具 |
| Reverse engineering | 26 个 dsh-re 工具和 ghidra（表格） |

MCP 服务器与 Ghidra

Settings → RE integrations 在 GUI 里管理这两者。里面有 Ghidra 桥接及其连接测试、已配置的 MCP 服务器及其实时状态，还有 GhidraMCP、radare2（r2mcp）、rizin、IDA Pro（ida-pro-mcp）、Binary Ninja 以及任何 streamable HTTP 服务器的模板。模板带着 <placeholders> 在编辑器里打开，不会下载任何东西。

Settings → RE integrations：Ghidra 桥接、MCP 服务器和模板

Ghidra 桥接。 GhidraMCP 插件在运行中的 Ghidra 里启动一个小型 REST 服务器。内置的 ghidra 工具直接连它，不需要 Python 桥接。这样智能体就能用反编译器、函数和数据列表、交叉引用、重命名、注释、原型和变量类型。在 Settings 里启用（存到 <home>/settings.json），也可以用 --ghidra / --ghidra-url URL，或者用 DSH_GHIDRA=1。Ghidra 必须处于运行状态并打开了一个程序。

MCP 服务器从两个文件读取。项目服务器会替换同名的用户服务器。

1. <home>/mcp.json（用户）；
2. <cwd>/.mcp.json（项目）。

支持两种传输方式：stdio（command）和 streamable HTTP（url）。不支持旧版 SSE。
json
{
"mcpServers": {
"ghidra": {
"command": "python",
"args": ["C:/tools/GhidraMCP/bridge_mcp_ghidra.py", "--ghidra-server", "http://127.0.0.1:8080/"],
"timeout": 120
},
"docs": {
"type": "http",
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }
}
}
}

| 字段 | 含义 |
| type | stdio 或 http；缺失时根据 command 或 url 推断。 |
| command、args、env、cwd | stdio 服务器。相对 cwd 按配置文件所在目录解析。 |
| url、headers | HTTP 服务器。 |
| timeout | 每次工具调用的秒数。 |
| startupTimeout | 秒数（默认 30）。 |
| parallel | 标记该服务器的工具可以安全并发运行。 |
| disabled | 跳过该服务器。 |

${VAR} 和 ${VAR:-default} 会在命令、参数、env 值、URL 和
标题。工具以 mcp__<server>__<tool> 形式出现，在 run_code 里可用。服务商提供资源时，会加上资源工具（list_mcp_resources、list_mcp_resource_templates、read_mcp_resource）。dsh-rs 会退避重连，工具列表的变更在下一个请求生效。

钩子

dsh-rs 运行 Claude Code 的 command 钩子。它从三个文件读取，顺序如下：

1. <home>/settings.json；
2. <cwd>/.claude/settings.json；
3. <cwd>/.claude/settings.local.json。
json
{
"hooks": {
"PreToolUse": [
{ "matcher": "bash|pwsh", "hooks": [{ "type": "command", "command": "python ${CLAUDE_PROJECT_DIR}/.claude/check_cmd.py", "timeout": 30 }] }
],
"PostToolUse": [
{ "matcher": "mcp__.", "hooks": [{ "type": "command", "command": "./log-mcp.sh" }] }
]
}
}

- 事件： PreToolUse、PostToolUse、UserPromptSubmit、Stop、SessionStart。
- 匹配器： 空匹配器或 匹配一切。由 [A-Za-z0-9_|] 组成的字符串是精确的择一匹配，比如 bash|edit。其他任何内容都按正则处理。
- 运行： 钩子从 stdin 拿到 JSON 载荷。在 Windows 上它跑在 Git Bash 里（回退到 cmd），其他地方跑在 bash -c 下。默认超时 600 秒。
- 结果：
- 退出码 2 会阻止该操作，stderr 成为原因。
- 退出码 0，且 stdout 上有 JSON 对象时，可以返回 decision、reason、continue、stopReason、systemMessage、hookSpecificOutput.permissionDecision（allow / deny / ask）以及 hookSpecificOutput.additionalContext。
- 多个钩子都给出结果时，deny 优先于 ask，ask 优先于 allow。
- 暂不支持 updatedInput。

每次钩子运行都会记进会话日志。

技能

技能是 <root>/<name>/SKILL.md（或平铺的 <root>/<name>.md），带 YAML front matter：name、description，以及可选的 disable-model-invocation: true。技能根目录按以下顺序搜索，先匹配到的胜出：

1. <cwd>/.claude/skills；
2. <cwd>/.agents/skills；
3. <home>/skills（RE 技能包安装在这里）；
4. ~/.claude/skills。

系统提示词会列出这些技能。模型用 skill 工具加载其中一个，参数是 {name, args?}；args 会替换正文里的 $ARGUMENTS。

AGENTS.md 和 CLAUDE.md

指令按从宽泛到具体的顺序收集：

1. <home>/AGENTS.md（或 CLAUDE.md）；
2. 从 git 根目录一直到工作目录的每一层，取 AGENTS.md / CLAUDE.md 中先出现的那个，再加上 AGENTS.local.md / CLAUDE.local.md 中先出现的那个。

内容重复的只收录一次，超过 1 MiB 的文件跳过。总量上限 64 KiB。

文件和存储位置

主目录是 $DSH_HOME，没设置时是 ~/.dsh-rs。

| 路径 | 内容 |
| sessions/<id>/session.v5.jsonl.zst | 只追加的会话日志（zstd 帧，格式 v5），附带 index.bin、meta.json 和 session.lock。 |
| spill/<session>/ | 大型工具结果（默认超过 50 KB）会溢出到上下文之外。 |
| logs/dsh-rs.<YYYY-MM-DD>.log | 每日日志，保留 7 份。过滤条件依次为 DSH_LOG、RUST_LOG，默认 info。 |
| logs/crash-<YYYYMMDD-HHMMSS>.log | 崩溃报告。 |
| providers.json、credentials.yaml | 服务商与默认路由（不含密钥）；API key（unix 下权限为 0600）。 |
| preferences.json | Settings → General：外观，以及新会话的默认值。 |
| mcp.json、settings.json、lsp.json | MCP 服务器；钩子与 ghidra 块；LSP 服务器。 |
| skills/、AGENTS.md | 技能（含 RE 包）与用户指令。 |
| cache/deepseek-files.json | Files API 上传缓存（只存哈希，绝不存 key）。 |

In each session's working directory, notes/findings.md is the findings notebook.

Skins are looked up in <exe dir>/skins, then ~/.dsh-rs/skins, then (debug builds only)
crates/dsh-gui/skins.

Environment variables

| Variable | Effect |
| DSH_HOME | The home directory. |
| DSH_LOG / RUST_LOG | The log filter (info, debug, dsh_core=trace, ...). |
| DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY | Provider keys. |
| DEEPSEEK_BASE_URL, ANTHROPIC_BASE_URL, OPENAI_BASE_URL | Base URL overrides. |
| DSH_LOCAL_BASE_URL, DSH_LOCAL_API_KEY | An extra local OpenAI-compatible provider. |
| DSH_GHIDRA, DSH_GHIDRA_URL, DSH_GHIDRA_TIMEOUT_MS | The built-in ghidra tool. |
| DSH_WEB_SEARCH_BACKEND, BRAVE_API_KEY, EXA_API_KEY | The web search backend. |
| DSH_BASH_PATH, CLAUDE_CODE_GIT_BASH_PATH | The bash used for the bash tool and for hooks on Windows. |
| NO_COLOR | Plain stderr in dsh-rs run. |

Performance

These are measured with Criterion (cargo xtask bench) on Windows 10 x64 on a shared, busy
machine, so treat them as upper bounds. Full tables are in docs/benchmarks.md.

| Path | Result | Target |
| Open a 127k-event session (lazy, newest 2,000 events) | 3.6 ms | < 15 ms |
| Open the same session in the agent core (OpenSession → SessionOpened) | 8.9 ms | < 15 ms |
| Build the next request after an 800-turn × 4-tool history | 146 µs | < 1 ms |
| run_code start → result | 274 µs | < 1 ms |
| PTC sub-call dispatch overhead | 24–32 µs | < 50 µs |
| In-process grep over 2,000 files (~10 MiB) | 19–49 ms | — |
| SSE parse of a DeepSeek stream | 823 MiB/s | — |

Troubleshooting

- "no API key" or 401 errors: run dsh-rs providers list and dsh-rs providers test deepseek. An environment variable overrides a stored key, so check that a stale DEEPSEEK_API_KEY is not set.
- Logs: look in <home>/logs/dsh-rs.<date>.log, and raise the detail with DSH_LOG=debug. Logs never go to stderr, because stdout and stderr belong to the stdio protocols.
- Crashes: dsh-rs writes <home>/logs/crash-<timestamp>.log and prints its path, and the GUI shows a dialog. The report has the version, OS, thread, panic message, backtrace, and the command line with secrets redacted. Distribution builds are stripped, so reproduce with a release build to get symbol names. Sessions are written continuously, and a torn tail is repaired on reopen.
- "dsh-rs GUI already running": one GUI runs per home directory. Use a separate DSH_HOME for a second one. run, sdk and acp always work next to the GUI.
- MCP server missing: check the status in Settings → RE integrations, or the log. A malformed mcp.json is skipped as a whole, and a server that fails 5 times in a row is marked failed. dsh-rs run --no-mcp rules MCP out.
- The ghidra tool fails to connect: Ghidra must be running with the GhidraMCP plugin enabled and a program open. Press Test connection in Settings, or check --ghidra-url.
- Blurry GUI or long-path errors on Windows: the exe manifest declares per-monitor DPI awareness and long-path support. Long paths also need LongPathsEnabled in the registry (Windows 10 1607+).

Development
sh
cargo test -p <crate> # unit and integration tests (no network)
cargo test -p dsh-conformance -- --nocapture # replay DeepSeek Harness's recorded scenarios
cargo xtask bench [--quick] # criterion benches (docs/benchmarks.md)
cargo run -p dsh-gui --example demo # GUI against a scripted fake core
cargo xtask dist [--no-skins] # dist/dsh-rs-<version>-<os>-<arch>.zip
cargo xtask third-party # THIRD_PARTY.md from cargo metadata
cargo xtask icon # regenerate the program icon

The demo takes flags for screenshots:

- --scenario demo|done|question|plan|stress|empty|settings
- --settings-general, --settings-re, --settings-mcp <preset>
- --tab <dock tab>, --palette, --shortcuts, --find , --attach <file>, --pin text|tool
- --skin <name> or --no-skin, --light, --size WxH
- --screenshot out.png

GitHub Actions CI builds and tests on Windows and Linux, and uploads the conformance report.
The crate layout and the ECS core are described in docs/architecture.md.

Licensing

- dsh-rs is MIT licensed (LICENSE). It ports the behaviour of DeepSeek Harness, which is MIT, Copyright (c) 2026 DeepSeek.
- The program icon is original work, drawn by cargo xtask icon, and is MIT.
- Skin artwork is not MIT. The orca-link and maid-atelier skins under crates/dsh-gui/skins/ are adapted from Small-tailqwq/dsh-deep-whale:
- their skin.json files and code-like parts are MIT;
- every image is CC BY-NC-SA 4.0: attribution, non-commercial only, share-alike. This includes the skinned screenshots in docs/img/.

Keep each skin's LICENSE, LICENSE-ARTWORK and NOTICE with its images. For commercial distribution, ship without skins/ (cargo xtask dist --no-skins); the GUI then uses its built-in theme. See crates/dsh-gui/skins/README.md.
- Third-party crate licences are summarised in THIRD_PARTY.md, which is generated into the release zip.