活体运行本 zhan-tz/dsh-plugin-runbook

运行手册

一个面向 DeepSeek Harness（DSH）的 Jupyter 形态研究界面。

凭感觉编码的研究项目会以远超人们重建来龙去脉的速度，堆积起脚本、图表、JSON 文件、终端日志和半成品目录。Runbook 为这些工作提供一个持久、由 Git 支撑的统一界面：研究问题始终可见，脚本始终有一个稳定的位置，每次运行都成为一条执行记录，每个输出都作为 Evidence 保持可追溯。

Runbook 刻意不做文件浏览器、不做第二个聊天记录、也不做魔法般的项目摘要。它是一层小小的投影，投射在 DSH、Git、项目文档和已观测文件中已经存在的事实之上。

核心思想

工作单元不是一个新文件夹，也不是像 final_v7 这样的文件名。

| 研究含义 | Runbook 投影 | 事实来源 |
| 我们试图决定什么？ | 问题 / 决策 / 开放问题指南针 | 人工撰写的 README.md 和 STATUS.md |
| 我们可以改变什么？ | 稳定的 Attempt 单元格 | 脚本路径及其当前 Git 工作树 |
| 发生了什么？ | 执行历史 | DSH 运行事实和会话谱系 |
| 它产出了什么？ | Evidence 世代 | 观测到的输出路径、元数据和可选哈希 |
| 这是哪个版本？ | 分支、提交和 agent 作者 | Git |

重新运行一个已有脚本，会向同一个单元格添加一次执行和一个输出世代。它不会创建另一个 notebook 页面，也不会鼓励再建一个日期目录。Git 仍然是版本系统；文件名仍然是地址，而不是版本。

当前界面包含什么

- 研究指南针 —— 问题、当前答案和下一个有区分力的步骤，同时人工撰写的来源仍然可见。
- 活的 notebook 单元格 —— 每个稳定脚本对应一个可读单元格。每个单元格将当前源代码、相关会话上下文、输出和先前的执行记录放在一起。
- 近期可视化结果 —— 来自活动会话谱系的最新图像、PDF 和 HTML 输出直接位于指南针下方，便于快速比较。
- 轮次局部产物 —— 由某轮对话产生的图像和 PDF 显示在该轮对话旁边，这样答案就不会与其图表脱节。
- 一条证据线索 —— 结构主干、会话运行、Git 提交、子代理和溯源事实会在调查需要更多细节时就地展开。不存在相互竞争的多个图页面。
- 安全重跑 —— Runbook 会准备一份清单，展示一次审查，并在执行受支持的脚本前要求一次短时有效的确认。

一个正常的研究循环

1. 在 DSH 对话中打开 Runbook / 运行本。
2. 在打开冗长的证据轨迹之前，先阅读指南针。
3. 当问题相同时，改进现有的 Attempt 单元格；只有当问题、数据、环境或输出契约确实不同时，才开启一个新分支。
4. 运行整个受支持的入口点，审查计划，并确认它。
5. 将新的 Evidence 与之前几代以及产生它的对话轮次进行比较。
6. 将有意义的检查点保存到 Git。Agent 可以自行编写提交；人类集成者可以继续作为提交者。

投影是如何构建的

authored README.md / STATUS.md ─┐
DSH session + ancestors ├─► one research workspace
observed executions / outputs ┤ compass → Attempts → Evidence
Git branch / commits / authors ┤ + one expandable evidence thread
bounded scan + optional PIPELINE ┘

项目事实池是持久的，但默认笔记本具有谱系感知能力：当前 DSH 会话可以看到自己的执行和祖先；同级会话会被保留但折叠起来。两个指向同一 cwd 的会话仍然共享物理工作树和项目事实池。真正的并发文件隔离需要 Git worktree 或独立的 DSH 工作区目标。

安装

从 GitHub：

dsh plugin --profile web add zhan-tz/dsh-plugin-runbook

重启所选的 DSH 界面，然后打开一个对话并选择 Runbook / 运行本。

用于本地开发：

git clone https://github.com/zhan-tz/dsh-plugin-runbook.git
cd dsh-plugin-runbook
dsh plugin --profile web add link:"$PWD"
npm test
npm run check

该包声明了 dsh.bundle.patch，因此正常的 DSH 插件安装会自动挂载所需的 Cordis 层。

安全与边界

- 浏览器从不调用任意的文件服务或 shell HTTP 路由。RPC 请求绑定到持久化的 DSH 会话，并且路径被限制在该会话的工作区内。
- 文本和媒体预览是有界的。内联媒体目前有 6 MiB 限制；不支持或更大的文件仍然可见，并可以在系统应用程序中打开。
- 重新运行使用宿主的运行器和会话工作区、环境允许列表、输出/时间边界以及一次性确认。Runbook 不暴露任意浏览器 shell，也不执行从 # %% 文件中截取的片段。
- 终端文本只是一种回退观察。完美的生产者/消费者溯源需要 DSH 工具或运行器发出结构化产物事件。
- 静态 I/O 检查和可选的 PIPELINE.md 主干只是提示，而不是对任意动态 I/O 的证明。

v0.18.0

此版本将最近的笔记本工作转化为一个连贯的公共界面：

- 一个集成的研究工作区，带有 Question → Decision → Open Question 指南针；
- 稳定的整脚本 Attempt 单元格和不可变的输出代际；
- 当前会话加祖先的投影，同级运行被折叠起来；
- 可读的步骤标题，同时保留精确路径以便审计；
- 感知 agent 的 Git 作者身份，而不覆盖人类/集成者身份；
- 最近的可视化结果和轮次本地的图像/PDF 产物在研究者实际查找它们的两个位置恢复；
- 会话绑定的预览、Git/结构检查、原生 DSH 子代理事实，并准备 → 审查 → 确认重跑。

中文说明

Runbook 不是把文件夹再画一遍，也不是把聊天记录压缩成一张“当前态”卡片。它把 DSH 的会话、Git、项目文档和实际观测到的输出，投影成一个适合反复实验的研究工作面：

- 顶部先回答“研究什么、现在判断是什么、下一步怎么判别”；
- 同一个脚本稳定占据同一个 Attempt 格子，重跑只增加历史和 Evidence 代；
- 当前 session 及祖先组成工作线，旁支事实保留但默认收起；
- 最近图片/PDF 在罗盘下方可见，生成它的回合旁边也有缩略图；
- 需要追溯时再展开同一条证据脉络，看运行、Git、subagent 和文件关系；
- 大文件、未知格式或暂时无法内联的结果不会消失，而是交给系统打开。

它鼓励 agent 先复用现有脚本、输出和 Git 历史，但不禁止真正独立的问题另开分支。

License

MIT