# 小黑盒 DSH 自动浏览与互动设计 ## 需求与范围 基于 `plasta2steel/dsh-xiaoheihe` v0.3.12 的签名与账号数据层开发。按用户最新要求,界面采用 `c1overzz/dsh-bili-scroll` 的设置页与会话标签方式:不使用侧栏、悬浮入口或遮罩。重新实现后台调度、去重和发送校验。 用户需要: 1. 定时任务总开关,可设置每隔多少分钟运行。 2. 每轮浏览一个或多个未处理帖子,可设置数量。 3. 自动评论开关。开启时根据帖子内容生成评论,并在评论中 @ 当前帖子的作者。 4. 自动回复开关,处理别人对自己评论的回复。 5. 可手动执行一轮,查看下次执行时间、运行状态、历史和失败原因。 6. 可选峰谷调度,降低模型调用成本。 “@ 作者”按当前帖子的作者账号生成,不能写死成插件使用者。使用平台支持的提及格式;仅拼接普通昵称不能宣称已产生提及通知。发送接口和提及格式需要依据可追溯源码验证,真实通知效果需登录账号联调。 ## 界面入口 - 通过 `settings.section` 注册「刷小黑盒」,在 DSH 设置中展示扫码登录(Cookie 备用)、总开关、间隔、每轮数量、评论 / 回复、谷时、人设、高级配置、状态和历史。采用「概览 / 账号 / 浏览 / 互动 / 评论记录 / 峰谷 / 高级」顶部 Tab 分类,通过公共操作栏统一保存全部菜单的改动;切换 Tab 保留编辑及扫码状态,窄屏菜单可横向滚动。 - 可选通过 `conversation.view` 注册独立 ID 的「刷过的帖子」标签;v0.9.0 起按账号持久化浏览档案,分页展示并链接到平台帖子。记录跨会话共享,不再依赖运行事件保留窗口。 - 沿用 DSH 主题、正常文档布局,适应窄屏;不挂载 `shell.overlay`,不检测或挤占聊天列宽度。 - 运行状态每 5 秒刷新,保留尚未保存的表单。离开页面清理轮询,后台任务继续运行。 - 参考插件分析版本仍为 `e46fd0081b0817951b809535f2425625c0398b24`,对应入口实现位于其根目录 `client.js`。 ## 设置 | 设置 | 初始值 | 说明 | | --- | --- | --- | | 定时浏览 | 关闭 | 登录并启用后才运行;不因安装自动发言 | | 执行间隔 | 30 分钟 | 按轮次执行,不并行,不补跑积压轮次 | | 每轮帖子数 | 1 | 可设 1–10,优先未读推荐帖 | | 自动评论 | 关闭 | 开启后根据正文生成相关评论 | | @ 作者 | 开启 | 自动评论时提及帖子作者;缺少作者信息则跳过发送 | | 自动回复 | 关闭 | 独立于主动评论额度 | | 每轮回复数 | 1 | 可设 1–10 | | 每日评论 / 回复额度 | 各 10 条 | 宿主强制限制,结果未知也暂占额度 | | 发送间隔 | 60 秒 | 评论、回复共用冷却,不能被手动执行绕过 | | 仅谷时调用模型 | 关闭 | Asia/Shanghai;窗口可配置,不假定所有供应商定价相同 | | DSH 命令 / profile | dsh / 固定 headless | 命令可编辑,默认使用 DSH 模型;0.10.0 可选第三方 API,密钥仅存独立 config.json | | 人设 / 兴趣 | 可编辑 | 第三方帖子和评论仅作为数据,不作为指令 | | 回复人格 | 留空 | 仅回复使用,留空继承通用人设;两项人设均支持多行、最多 2000 字符 | 配置校验拒绝不合法数值,不用静默截断掩盖输入错误。界面保存配置后,宿主重新计算下次执行时间。关闭开关后取消当前生成任务,并在发送前再次核验开关;已提交给平台的请求无法撤回。 ## 架构 后台运行依赖 DSH 宿主进程持续运行,关闭浏览器面板不影响任务,退出 DSH 后不运行。不安装系统级定时器。 ```text 定时器 / 手动执行 -> 宿主互斥锁 -> 登录、时间窗口和预算检查 -> 获取推荐 / 消息,结构化去重 -> 按需读取帖子及相关对话 -> DSH 生成结构化决策(不直接持有发送权限) -> 宿主校验目标、额度、冷却、配置版本 -> 小黑盒签名请求 -> 保存回执、状态和运行记录 ``` DSH 只产出评论决策和正文。发送由宿主统一执行,没有模型可传入的 `force` 越权参数。模型输出错误、超时或无足够上下文时跳过,不用固定套话补发。初期保持 Node.js 实现,不引入 B 站 Python MCP、视频转写等依赖。 ## 调度与峰谷 - 持久化下次执行时间;到期只运行一轮,重启不补刷。 - 单实例互斥,生成任务超时终止;多宿主使用文件锁,避免同一账号状态目录重复执行。 - 启动失败记录错误并按间隔重试,不预先消耗整个时间窗口。 - 可选谷时:北京时间工作日 12:00–14:00、18:00–次日 09:00,以及周末全天;法定节假日通过可配置日期补充,补班日期也可覆盖。设置页明确这是本地策略,并非自动查询供应商价格。 - 使用实际时间点判断,无“自然日夜间窗口”标记,因此不产生凌晨占用傍晚名额的问题。 - 主动浏览和回复分别计数,浏览额度用完不会直接阻止回复。 ## 互动与记录 - 同一账号在同一帖子下最多自动发一条主评论;记录发出的平台评论 ID。 - 同一条来信只处理一次,使用平台消息 / 评论 ID 去重,不依赖昵称和文本匹配。 - 只对能确定是回复自己评论的消息自动回应;不能确定目标关系时记录跳过原因。 - 不回复自己的评论;无法确认当前账号 ID 时不执行自动发送。 - 发送前写入持久化意图,收到明确结果后写回。超时或进程中断标记“结果未知”,不自动重发。 - 保存已读帖子、互动结果、每日额度和最近运行记录。日志不含 Cookie、模型凭据或完整命令提示词。 - 复核只能报告接口可查状态;无法确认公众可见时不标为“公开成功”。 - 发送意图同时持久化实际提交正文、帖子标题和回复来信,即使回执超时也可查看。状态接口仅返回当前账号最近 100 条互动,跳过项不进入评论记录;旧版没有保存的正文不回填。 ## 依赖与环境 - 高级菜单检测宿主 Node、已保存的 DSH 启动命令、npm 及二维码依赖;不修改全局模型配置。 - 一键安装仅接受固定操作,在 `$DSH_HOME/heybox/dependencies` 安装 `qrcode@1.5.4`,禁用 npm 安装脚本,不接受客户端传入的命令或包名。 - 安装在宿主后台执行,禁止重复启动,最多等待 180 秒;状态轮询展示进度、完成或失败。离开网页不取消,宿主退出时终止子进程。 - 优先加载插件原有依赖,缺失时动态加载本地补装依赖,无需重启。安装后验证二维码模块可加载。 ## 实施与验收 1. 接入底座,抽取宿主签名 API,验证发评论 / 回复 / @ 格式来源。 2. 实现持久化设置、定时轮次、互斥锁、超时与结构化记录。 3. 接入 DSH 决策、自动评论 @ 作者和回复流程。 4. 注册设置页和可选会话标签,增加手动执行、运行状态和历史。 5. 使用假 API / 假 DSH 验证定时、去重、额度、停止、未知结果和峰谷边界,运行底座原有检查。 6. 真实账号联调单独标注结果;没有平台凭据时不声称验证了真实发送或通知。 ## 来源 - 底座:https://github.com/plasta2steel/dsh-xiaoheihe ,分析版本 `32bc17d707397af48368db759548806763bca6aa`,MIT。 - 任务组织参考:https://github.com/c1overzz/dsh-bili-scroll ,分析版本 `e46fd0081b0817951b809535f2425625c0398b24`,MIT。 - 保留底座 LICENSE 与原始致谢。新实现独立编写;无许可证的第三方代码仅用于理解接口,不复制实现。 实现细节与剩余联调项见后续开发记录。 ## 实现后的边界说明 首版已实现,见 [development.md](development.md)。官网当前 Web 编辑器把输入转换成纯文本,再通过评论接口提交,未找到可验证的专用提及参数。因此本版实际使用 `@作者昵称 正文`,UI 明示“提及通知尚未验证”;不能把此能力当作已完成的站内 @ 通知。真实通知格式仍需账号联调或补充官方契约。 当前回复扫描上限为最近 100 条消息,每个相关根评论最多检查 5 页子评论,目标关系不确定则跳过。该范围外的历史消息不保证覆盖。帖子去重与浏览档案长期保留,运行历史只保留最近 200 条,界面显示最近 40 条。浏览档案通过 `/heybox/watched` 每页 50 条读取。状态随互动次数增长,后续可增加归档。 首版以读取帖子详情作为“浏览”;不保证平台浏览计数增加。只读模式不调用模型;自动评论和回复通过 DSH headless 生成。谷时开关目前限制整轮执行。手动执行同样要求总开关开启并遵守谷时 / 额度 / 冷却。 ## 0.10.1 自定义时间段 新增不限时段、峰谷与峰底快捷预设,应用后仍可逐段修改。工作日使用 valleyWindows,周末使用 weekendWindows,节假日使用 holidayWindows;三组均支持空数组(不运行)、[0,1440](全天)及跨午夜。补班日按工作日处理,节假日优先。旧配置自动获得周末、节假日全天的默认值,保留原行为。峰底 00:00–06:00 仅为示例,不查询或承诺供应商定价。