dsh-suhuang-scroll（苏黄共阅）
dsh-suhuang-scroll 是一个 DSH Web 插件，把本机 Suhuang Scroll Runtime 接入 DSH 的设置主菜单，并在 Better Sidebar 中提供简洁的阅卷控制台。
插件负责配置、状态展示和人工控制。评分规则、Spec 解析、任务状态和网站适配器仍由 Suhuang Scroll Runtime 与浏览器扩展负责。
使用前准备
需要依次准备：
- 已能运行的 DSH Web。
- Suhuang Scroll Runtime。
dsh-better-sidebar。它是运行控制台所在的侧边栏底座。- 本插件
dsh-suhuang-scroll。
macOS 和 Linux 可用官方安装器安装或升级 Suhuang Scroll Runtime：
curl -fsSL https://raw.githubusercontent.com/YZDame/SuhuangScroll/main/scripts/install/install.sh | bash
安装器会校验发布包并默认安装到 ~/.local/suhuang-scroll。如需先审阅脚本，可下载后再执行。Windows 安装方法见 Suhuang Scroll 安装文档。
安装 DSH 插件
在 DSH 所在环境的终端执行以下一行命令。它会先安装 Better Sidebar，再安装苏黄共阅插件，并自动把两个 bundle 加入 Web profile：
cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar && dsh plugin --profile web add dsh-suhuang-scroll
完成后重启 DSH Web，并在浏览器中硬刷新页面。打开 DSH 设置主菜单中的“苏黄共阅”，再从 Better Sidebar 的 + 菜单打开“苏黄共阅”Tab。
从 GitHub 安装开发版时，将最后一个包名替换为：
git+https://github.com/YZDame/dsh-suhuang-scroll.git
首次配置
- Runtime API 默认使用
http://127.0.0.1:8000/api，一般无需修改。
- 选择评分标准和阅卷平台适配器。
- 在“模型服务商”中填写 Base URL、模型 ID 和 API Key。
- 点击“测试连接”。连接测试只读取 OpenAI 兼容服务的
/models，不会启动阅卷。
- 保存设置后，打开侧边栏中的苏黄共阅控制台。
插件会依次查找用户填写的后端位置、SuhuangScroll 源码目录以及 ~/.local/suhuang-scroll 下的标准 Runtime。使用自定义安装目录时，在设置中填写安装根目录或 core/python 目录。
阅卷控制
- “启动苏黄共阅”只启动本机 Runtime，不会自动开始阅卷。
- “开始阅卷”经过确认后启动连续阅卷，默认逐份处理并自动进入下一份，直到队列结束、用户暂停、用户结束或发生错误。
- “暂停阅卷”会请求在安全节点暂停；按钮随即进入“正在暂停”。暂停完成后可点击“继续阅卷”。
- “结束本次阅卷”会终止当前连续任务，不会关闭由其他程序启动的 Runtime。
- Runtime 由插件启动时，可以在没有运行任务的情况下从“连接详情”停止服务。
真实阅卷会根据 Spec 和置信度阈值自动提交符合条件的成绩。开始前请确认评分标准、模型配置和目标阅卷平台；不要在测试环境中使用真实学生数据。
功能概览
- DSH 设置主菜单中的“苏黄共阅”配置页。
- Runtime API、Spec、适配器、模型服务商、Base URL、模型 ID、API Key 和置信度阈值配置。
- 模型连接测试以及 Runtime、资源和协议版本检查。
- Better Sidebar 单实例运行 Tab，展示任务阶段、完成数量和用时。
- 连续阅卷的开始、暂停、继续、结束，以及插件管理的 Runtime 启停。
- 浅色与深色模式自适应。
未安装 dsh-better-sidebar 时，设置页仍可加载，但不会注册侧边栏运行 Tab。
更新与卸载
更新插件及其前置依赖：
cd ~/.dsh && dsh plugin --profile web add dsh-better-sidebar@latest && dsh plugin --profile web add dsh-suhuang-scroll@latest
卸载插件：
cd ~/.dsh && dsh plugin --profile web remove dsh-suhuang-scroll
只有在没有其他插件使用 Better Sidebar 时，才继续执行：
cd ~/.dsh && dsh plugin --profile web remove dsh-better-sidebar
卸载 DSH 插件不会删除 Suhuang Scroll Runtime、模型配置、Specs 或阅卷记录。
常见问题
显示“未找到苏黄共阅 Runtime”
先运行 suhuang doctor。使用非默认目录安装时，在设置中填写安装根目录或包含 main.py 的 core/python 目录，然后重新点击“启动苏黄共阅”。
测试连接显示 Not Found
确认 Base URL 指向 OpenAI 兼容接口的服务根路径。插件会让 Runtime 请求该地址的 /models；部分服务需要在 Base URL 中包含 /v1。
点击继续阅卷时提示后端不可用
展开“连接详情”检查 Runtime 状态。若旧进程由其他程序启动，先在原终端结束旧进程，再由侧边栏启动当前版本。
页面里没有“苏黄共阅”Tab
确认 dsh-better-sidebar 和 dsh-suhuang-scroll 都已安装到同一个 web profile，然后重启 DSH Web 并硬刷新浏览器。
本地开发
在 SuhuangScroll 仓库根目录执行：
dsh plugin --profile web add "$PWD/plugins/dsh-suhuang-scroll"
dsh --profile web --dump-config
默认允许 http://127.0.0.1:3080 和 http://localhost:3080 访问本机 Runtime。自定义 DSH 端口时，在 Runtime 环境中追加精确的 ALLOWED_ORIGINS，不要使用 *。
安全边界
- Runtime API 只接受 loopback 地址，不接受账号、密码、查询参数或非本机域名。
- 远程模型 Base URL 必须使用 HTTPS；本机模型服务可以使用 HTTP。
- API Key 直接发给本机 Runtime，保存在系统用户配置中，不写入 DSH profile，也不会在接口中回显。
- 状态读取和连接测试不会开始阅卷；开始与结束操作需要 UI 确认。
- 插件不会强行终止由其他程序启动的 Runtime。
许可证
Apache License 2.0
