dsh-code-runner · 代码运行器（v7 · 0.7.0）
DeepSeek Harness (DSH) 插件：在 对话框右侧 打开一个 RStudio 风格的代码工作台，直接运行
Python、R、Node.js 等脚本，图表自动显示，并且可以 打开 / 编辑 / 保存工作目录里的程序文件。
不必离开和 DeepSeek 的对话。
- v7 新增：导入数据集（仿 RStudio） —— 工具栏「数据集」可直接打开 Excel .xlsx / CSV / TSV
数据文件，表格预览（工作表切换、列类型、日期识别、首行为列名、分隔符），并一键生成
R / Python / MATLAB 导入代码插入编辑器（不依赖 Excel/pandas 插件安装，.xlsx 由 Host 纯 Node 解析）。 - v6：导出报告可选图表位置 —— 图表既可以放在「统计图：」独立章节（默认：
源代码 → 输出结果 → 统计图），也可以跟随源代码放在对应代码下方（源代码 → 统计图 → 输出结果）；
Word / Markdown / HTML 三种格式一致，Word 中从属关系用二级标题表达。 - v5：语言功能包按需安装 —— 检测到本机有某语言才自动启用并安装其图形捕获程序（没有就不加任何文件）；
语言下拉旁「语言与功能」可一键启用/停用；可选包 C / C++ / Swift（检测到工具链后可一键安装，C/C++ 先编译再运行）；
Python 捕获依赖（matplotlib）自动探测并给出安装提示。 - v4：导出报告可选格式（Word .docx / Markdown / HTML / 全部）、文件名自动为
<程序名>实验报告、可勾选是否插入源代码 / 输出结果 / 统计图 / AI 解读，文档按
「源代码：/ 输出结果：/ 统计图：」结构输出；Word 由 Host 用纯 Node 生成（无需 Office/pandoc）。 - v3：运行选中的代码；AI 自动注释/解释代码（使用 DSH 默认模型）；一键把「代码 + 输出 +
图表 + AI 解读」导出为文档文件夹（report.md + 自包含 report.html）；MATLAB 支持（R2026a 自动发现、
figure 自动导出）；图表一键保存到代码所在文件夹；切换语言时界面自适应（控制台名称、提示、模板、
扩展名、MATLAB 启动提示）。 - v2 能力：右侧栏面板（对话与代码同屏）、图表画廊（matplotlib / R / MATLAB 图形自动捕获）、文件
浏览器与编辑器（打开、⌘S 保存、冲突检测、直接运行磁盘文件）。 - v1 能力：左侧栏入口 + 中央全屏工作台、流式输出、停止/超时、语言探测、token 安全闸门。
两个入口
| 入口 | 形态 | 适合 |
|---|---|---|
| 对话右上角 代码运行器图标（或右侧栏「+」→「代码运行器」） | 右侧栏 tab，与对话并排 | 边聊边跑、看图表 |
| 左侧栏「代码运行器」图标（order 30） | 中央全屏页面 | 大屏、RStudio 式三栏布局 |
右侧栏 tab 里是紧凑模式：顶部工具栏（文件、保存、运行/停止、语言、工作目录）、带行号的编辑器、
可拖动分隔条、底部 控制台 / 图表 / 文件 三个标签页以及一行状态栏。全屏页面模式则把
「文件/图表」放进左侧栏、编辑器和控制器上下排列。
升级到 v2 后 首次加载会在这个浏览器里自动打开一次右侧工作台（localStorage 标记
dsh-code-runner.autopened.v2，只一次）；之后右侧栏按会话记住你上次的开/关与标签布局，
头部图标则用于随时展开/收起。
功能
运行
- 自动探测本机解释器：Python 3.13.9、R 4.6.1、MATLAB R2026a、Node v24、Bash、Zsh、Ruby、Perl（Julia/Deno/Bun/PHP
未安装时自动隐藏，可「重新扫描」）。 - 运行编辑器内容（scratch buffer）或 运行打开的文件：打开文件后 Run 会先自动保存再以
mode:"file"直接在磁盘上执行（scriptPath就是该文件，__file__/相对路径行为与命令行一致）。 - 流式 stdout/stderr、退出码/信号/超时/耗时、停止按钮、⌘/Ctrl+Enter 运行、⌘/Ctrl+S 保存。
- 工作目录会持久化，可用「选择…」从系统目录选择器挑选；每个语言保留独立草稿。
运行选中的代码（v3）
- 在编辑器里选中若干行，点工具栏 运行选中（或
⌘/Ctrl+Shift+Enter），只执行选中的片段
（以 buffer 模式在相同工作目录/语言下运行，编辑器内容不受影响，控制台会标记「选中运行」）。 - 适合 R/Python 交互式探索：先定义变量，再选几行逐步运行。
AI 注释 / 解释代码（v3）
- 工具栏 理解 / 注释代码：把当前代码（有选中时用选中部分）发给 DSH 的默认模型，返回
中文解释 + 带注释的代码版本；可 插入注释版本到编辑器（一次撤销可还原）、复制解释。 - 模型来自 设置 → 模型（默认
deepseek-account/deepseek-flash）。未配置模型时对话框会提示
「先在 DSH 设置里配置模型/提供商」；网络/超时错误会给出可重试的提示。 - 代码超过 20,000 字符会截断后发送（对话框会标注）；请求经过 Host，token 门禁与其它接口一致。
导出运行报告（v3）
- 工具栏 导出报告 打开导出对话框，可选择：
- 文件格式：Word（
.docx，默认）、Markdown（.md）、HTML（.html，图表内嵌）、全部格式； - 插入内容：源代码 / 输出结果 / 统计图 / AI 解读（逐项勾选，不需要的不会写进文档）；
- 文件名：自动为「程序文件名 + 实验报告」，例如
chart.R→chart实验报告.docx； - 图表位置（v6）：独立章节（默认）/ 跟随源代码（图表放在对应代码下方）；未勾选统计图或本次
没有图表时该选项置灰。Word 跟随源代码时「统计图：」用二级标题（Heading2）表达从属关系。 - 报告写入 代码文件所在目录（草稿则在当前工作目录）下的新文件夹：
dsh-code-runner-reports/<时间戳>-<语言>/，其中文档结构固定为 源代码：/ 输出结果：/ 统计图：
（勾选了 AI 解读时追加「AI 解读：」）；Word 中代码/输出用等宽字体、统计图内嵌为图片并带图注。
另含run.json元数据与plots/图片副本；同一秒重名文件夹自动-2，绝不覆盖旧报告。 - 每次导出都新建文件夹（同一秒重名自动
-2），不会覆盖旧报告；这些文件夹是用户文档，插件不会删除。
成功后会显示路径并提供「复制路径」，状态栏也保留可点击的报告目录入口。
导入数据集（v7，仿 RStudio）
- 工具栏 数据集 → 「导入数据集（仿 RStudio）」对话框：
- 数据文件：输入/粘贴绝对路径回车读取，或从下方目录浏览（文件夹、
.xlsx/.csv/.tsv/.txt
数据文件；支持上级与刷新）。 - 预览（RStudio 风格）：Excel 多工作表下拉、首行为列名开关、CSV 分隔符（自动/,/;/Tab/|）、
行×列摘要与前 20 行表格；列类型自动识别（文本 / 数字 / 布尔 / 日期，Excel 日期按样式还原）。 - 导入代码：按当前语言生成，插入到编辑器（追加到现有代码末尾，可撤销）或复制：
- R：
library(readxl)+read_excel("…", sheet = "…")（csv 为read.table/read.delim） - Python：
import pandas as pd+pd.read_excel(..., sheet_name=…)/pd.read_csv(...) - MATLAB：
readtable("…", 'Sheet', "…") - 读取完全只读，不修改/复制数据文件；旧版
.xls会提示先另存为.xlsx/.csv（无外部依赖，
.xlsx由 Host 用 zlib 解析 OOXML）；大文件预览上限 64 MiB、20 行预览。
MATLAB 支持（v3）
- 自动发现
matlab（含/Applications/MATLAB_R*.app/bin/matlab、/usr/local/MATLAB/*/bin/matlab）；
R2026a 已在本机验证：-batch执行包装脚本，运行后把每个figure用exportgraphics导出到
图表页（source:runPNG）。 - 注意事项：MATLAB 需要本机许可证且首次启动较慢（约 15–25 秒，界面会显示「正在启动 MATLAB…」）；
未安装时该语言自动隐藏。包装脚本变量统一用dsh*前缀，避免 MATLABrun()与script变量名冲突。
图表保存与呈现（v3）
- 图表卡片悬停出现 保存；灯箱底部有 保存图片；图表页头部有 全部保存。
- 默认保存到 当前打开代码文件所在文件夹（无文件时为工作目录），重名自动加
-1/-2，绝不覆盖；
成功提示会显示目标文件夹，状态栏保留可点击入口。 - 呈现升级：页面模式更大的图表网格、文件名/来源/大小信息、灯箱元信息、加载骨架与空状态。
语言自适应界面（v3）
- 切换语言时界面自动适配：控制台/命令窗口名称、工具栏下的提示条、启动模板、另存为默认扩展名、
状态栏语言名；MATLAB 额外显示启动提示，Python/R 显示绘图捕获提示。
图表（类似 RStudio Plots）
- Python：脚本里
import matplotlib.pyplot as plt并画图（不需要 savefig），运行结束后图形
自动保存为 PNG 并出现在「图表」标签页；plt.show()在 Agg 后端下无副作用。 - R：
plot(...)、ggplot2 等图形由png设备自动捕获（脚本无需写png()/dev.off()；顶层可见结果会自动打印，与Rscript script.R一致，所以直接写ggplot(...) + geom_*()就能出图，无需print()）。 - 另外，脚本在 工作目录 里新写出的图片（png/jpg/gif/webp/svg/bmp/avif）也会出现在图表页，
带「运行产物 / 目录」来源标记。 - 缩略图网格，点击打开灯箱：大图、上一张/下一张、复制路径、Esc 关闭；运行过程中每 1.2 秒自动
刷新，新图出现会自动切到图表页；「刷新」按钮可手动重新扫描。 - 需要自己
savefig/png()的脚本也能用：文件会作为「目录」来源被扫描到。
文件（直接打开工作文件夹里的程序）
- 「文件」标签页：面包屑、上一级、刷新、目录优先排序、点目录进入、点文本文件打开到编辑器
（按扩展名自动选语言：.py/.R/.mjs/.sh/.rb/.pl/.jl/.php/.ts …）。 - 打开图片文件会直接在灯箱预览；二进制文件给出提示。
- 保存：按钮或 ⌘/Ctrl+S，带
baseMtimeMs冲突检测——文件被外部改动时提示「覆盖 / 取消」后强制保存。 - 草稿缓冲区可「另存为」到当前工作目录，随后自动切换为文件模式。
- 有未保存修改时切换文件会先确认（放弃 / 取消）。
HTTP API（Host 半，同源 + token 门禁）
| Method | Path | 用途 |
|---|---|---|
| GET | /dsh-code-runner/api/env |
平台、默认目录、上限、本机语言/版本/模板（?refresh 跳过缓存） |
| POST | /dsh-code-runner/api/run |
{mode:'buffer'\|'file', language?, code?, file?, cwd?, stdin?, timeoutMs?, capturePlots?} → {runId, plotDir, …} |
| GET | /dsh-code-runner/api/output |
?runId=&stdoutFrom=&stderrFrom= → 增量输出 + 状态 |
| POST | /dsh-code-runner/api/stop |
{runId} 终止进程 |
| GET | /dsh-code-runner/api/files |
?dir= 列目录（目录优先、2000 条上限） |
| GET | /dsh-code-runner/api/file |
?path= 读文本（1 MiB 截断、二进制检测） |
| POST | /dsh-code-runner/api/file |
{path, text, baseMtimeMs?} 保存（409 冲突 / 强制覆盖） |
| GET | /dsh-code-runner/api/blob |
?path= 图片/PDF 原始字节（唯一非 JSON 路由） |
| GET | /dsh-code-runner/api/artifacts |
?runId= 本次运行的图表（运行产物 + 工作目录图片） |
| GET | /dsh-code-runner/api/token |
仅 loopback 的 CSRF token bootstrap |
| GET/POST | /dsh-code-runner/api/diag |
浏览器诊断事件（内存储环缓冲，排障用） |
| POST | /dsh-code-runner/api/explain |
{language, code, fileName?} → AI 解释 {summary, annotatedCode}（需已配置模型） |
| POST | /dsh-code-runner/api/export |
{format:'docx'\|'md'\|'html'\|'all', include:{code,output,plots,summary}, name?} → <程序名>实验报告. + run.json/plots |
| POST | /dsh-code-runner/api/save-plots |
{plots, targetDir} → 图表复制到代码文件夹（去重不覆盖） |
所有调用（除 /api/token）都要带 x-dsh-code-runner-token，值来自 Host 注入页面的
window.__DSH_CODE_RUNNER__（页面在插件激活前加载时自动走 loopback bootstrap）。跨站请求被拒绝，
没有 CORS。
安装 / 升级
本机已作为本地 bundle 安装（link:/Users/sunchujun/Desktop/deepseek/dsh-code-runner）：
plugin_manager action=install_bundle target=<绝对路径>/dsh-code-runner
修改源码后无需重启：Host 与 Client 代码由 HMR 从链接目录热加载（插件管理器的一次重算也会替换
已改动的文件的插件）。其他部署用同一份目录安装即可。
开发与测试
无构建、无第三方依赖：直接改 index.js / client.js，node --check 后热加载。
| 套件 | 内容 | 当前 |
|---|---|---|
node tests/host-smoke.mjs |
Host 路由契约 + 真实 python/R/绘图 + 文件/诊断/语言包/报告图表位置/数据集预览接口（stub ctx） | 51/51 |
node tests/verify-host.mjs |
独立实现的 stub Host 契约套件（含 explain/export/save-plots/MATLAB 规格、报告图表位置三格式顺序、数据集 xlsx/csv 解析、90s 超时） | 102/102 |
node tests/verify-static.mjs |
manifest/locale/图标/两半静态契约（含 v3/v6/v7 标记与 locale 键） | 92/92 |
node tests/verify-live.mjs |
对运行中的 DSH 做端到端（真实 LLM explain、Word/MD/HTML 报告导出、图表保存、真实 MATLAB 运行+出图、报告图表位置、数据集预览（xlsx/csv）、选中运行语义） | 45/45 |
tests/client-real-react.mjs（可选，需 react/react-dom/jsdom） |
真实 React 18 + jsdom 渲染两种布局 + StrictMode + 主流程点击；捕获 VM 测不出的 React #130 | 17/17 |
node tests/client-smoke.mjs |
VM 内渲染真实 client 模块（注册、两种布局、文件/图表/灯箱、选中运行、AI 对话框、导出格式、语言与功能对话框、图表位置选择、数据集导入对话框、图表保存、语言自适应、元素类型守卫、诊断） | 107/107 |
契约：CONTRACT.md（v1）+ CONTRACT-V2.md（文件/绘图）+ CONTRACT-V3.md（AI/导出/图表/MATLAB/选中）+ CONTRACT-V5.md（语言功能包按需安装）+ CONTRACT-V6.md（报告图表位置）+ CONTRACT-V7.md（数据集导入）。
> 回归守卫：client-smoke 的迷你 React 会像真实 React 一样拒绝非法元素类型（React #130），
> 例如把 h(组件) 误写成 h(组件())；v2 首次上线时正是这类写法导致右侧面板报「面板出错了」，
> 已修复并用真实 React 18 + jsdom 的渲染/交互复现验证。
故障排查
右侧面板/全屏页如果显示「面板出错了」：先刷新页面。之后可以从命令行读取浏览器诊断，
看清真实页面发生了什么（加载了哪个版本、右侧 tab 类型是否注册、面板是否挂载、有没有崩溃事件）：
TOKEN=$(curl -s http://127.0.0.1:57598/dsh-code-runner/api/token | python3 -c 'import json,sys;print(json.load(sys.stdin)["token"])')
curl -s -H "x-dsh-code-runner-token: $TOKEN" http://127.0.0.1:57598/dsh-code-runner/api/diag | python3 -m json.tool
事件名：apply（客户端版本 + 右侧栏服务是否可用）、right-tab（tab 类型/面板注册结果）、
header-toggle、auto-open、toggle、surface-mount / surface-unmount、
surface-crash（错误边界捕获的崩溃及组件栈）、run、artifacts。缓冲仅最新 100 条、
仅内存、随页面/Host 重载清空。
安全说明
这是本机代码执行 + 文件读写能力：Host 端有 CSRF token（仅注入页面 / loopback bootstrap）、
Origin 同源校验与跨站拒绝，且没有 CORS。/api/token 只应答 loopback 对端 + loopback Host 头，
反向代理/隧道呈现公网 authority 时会被 403 拒绝。请勿把 DSH Web 服务暴露到不可信网络。
卸载
设置 → 插件 → Code Runner 移除，或 plugin_manager action=remove_bundle。运行临时目录
（脚本副本、绘图中间产物）会随插件卸载/运行淘汰清理；工作目录里的用户文件永远不动。
License: MIT.
