@songxiyuan/dsh-tracebook

v0.1.0

Published

a month ago

DeepSeek Harness plugin for organizing persistent engineering investigation cases

0High
0Medium
0Low

songxiyuan

dsh deepseek-harness plugin bundle investigation case viewer

Tracebook

Tracebook 是运行在 DeepSeek Harness（DSH）上的工程调查结果组织插件。它把 Agent 已经理解出的结果保存为可持续更新的结构化 Case，并提供 Artifact 管理、交互式 Viewer 和跨 Session 上下文复用。

当前状态：MVP 已实现，并已在 DSH 0.1.5-rc.3 Web Profile 中完成真实运行验证。Agent 负责探索，Tracebook 负责规范化、持久化、展示与复用。

MVP 能力

tracebook_open：创建或恢复 Case，并关联当前 Session。
tracebook_update：按稳定 block.id 增量 upsert，支持 revision 冲突保护。
tracebook_context：返回适合后续 Agent 使用的压缩 Context。
DSH Domain Storage：Core 只依赖 CaseRepository，DSH 细节集中在 Host adapter。
文件 Artifact Store：原子写入 Screenshot、Log、HTTP、Trace、HAR 等原始资料，Case 仅保存元数据与引用。
同源只读 API：Case List、Case Detail、Blocks、Artifact 内容、Session 关联与 Revision 历史。
Vue 3 Viewer：Case 列表/搜索、Block 搜索、Case 文档、八种 Block Renderer、API 接口详情（输入输出 / 耗时来源 / HAR 单次请求瀑布）、表格筛选、Artifact 类型筛选与内嵌预览、Gallery、Evidence。
视觉系统：白色页面 + Archify 风格的平面 + 1px 描边 + mono 前置 + 语义色，高密度信息布局（规范见设计文档 13.1）。
Vue Flow + ELK.js：流程渲染、自动布局、缩放、Minimap、Node Inspector 与 Layout 切换；Node Inspector 内嵌节点图片 Artifact 缩略图。
更新提示：轮询 revision，提示新版本并在刷新时保留滚动位置与 Flow 选中项。
Ask about this：从 Flow Node / Evidence / API endpoint 携带上下文回到当前 DSH 对话输入框（只填入草稿，不自动发送）。
DSH 原生入口：会话标题栏 Tracebook 按钮，经 Right Sidebar 打开当前 Session 的 Case。

支持的 Block：markdown、facts、flow、table、timeline、evidence、gallery、api。

api Block 承载接口清单与详情：每个 endpoint 可带 request（params / body）、responses（状态码 / 示例 / Artifact 引用）与 timing。协议对「数据从哪来」是强约束的：

timing.source 必填（trace / har / log / metrics / estimated），Viewer 把实测与「估算」分开呈现。
任何 example 必须带 source（observed / spec / inferred），编造的示意值和真实抓到的响应不会长得一样。
分位数必须带 sampleSize 与 errorCount（RED），错误率由二者推导；window 界定聚合区间。
声明耗时（SLO）用 endpoint 上的 expectedMs / expectedRef，与实测分开；只有声明过的阈值才会给数字上色。
当 timing.source 为 har 且 artifactRef 指向 HAR Artifact 时，展开 endpoint 会用 @cloudflare/waterfall 画单次请求瀑布；无法读取或无匹配请求时回退到相位汇总条。渲染器与样式按需懒加载，不进主 bundle。

协议细节见设计文档 7.8 节；为什么不复用 OpenAPI 渲染器见决策记录。

安装

Tracebook 以 DSH Bundle 形式装载：不引入第二套 runtime，也不修改 DSH Web。

| 前置条件 | 要求 | | --- | --- | | Node.js | ≥ 22 | | DSH | npm i -g @deepseek-ai/dsh，需提供 dsh 命令 | | pnpm | dsh plugin 是 pnpm 的薄转发器，用 PATH 上的 pnpm |

方式 1：从 npm 安装（推荐）

dsh plugin --profile web add @songxiyuan/dsh-tracebook
dsh --profile web --dump-config      # 组合后的配置树里应出现 tracebook 行
dsh web

包内已含构建产物（dist/index.js、dist/client.js、dist/web/），目标机器不需要 Node 构建环境，也不需要额外的构建脚本授权。

方式 2：从源码安装

改代码、跟主干时用这条，后续 git pull 即可升级。

git clone https://github.com/songxiyuan/tracebook.git
cd tracebook
npm ci                               # prepare 钩子自动构建 dist/
dsh plugin --profile web add "$(pwd)"
dsh --profile web --dump-config
dsh web

dsh plugin add 接受包名、tarball、本地目录等 pnpm 支持的写法。本地目录会被锚定为 link: 依赖，命令结束时把 dsh.profile.bundles 与被安装的依赖状态对齐——Tracebook 声明了 dsh.bundle，所以会自动进入层栈，不需要手改 profile 的 package.json：

{
  "dependencies": { "@songxiyuan/dsh-tracebook": "link:/path/to/tracebook" },
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@songxiyuan/dsh-tracebook"] } }
}

link 安装会保留源码仓库的真实路径，Node 优先从仓库自己的 node_modules 解析 DSH 能力包，因此仓库 lockfile 固定了与 DSH 0.1.5-rc.3 对齐的完整 peer graph。不要使用 --legacy-peer-deps：跳过这些传递 peer 会让直接依赖遮蔽宿主包，插件启动时报 ERR_MODULE_NOT_FOUND。

目标机器没有构建环境时，先在有源码的机器上打包，再把 tarball 拷过去（约 670 KB）：

npm pack                             # → songxiyuan-dsh-tracebook-0.1.0.tgz
scp songxiyuan-dsh-tracebook-0.1.0.tgz user@other-machine:/tmp/
dsh plugin --profile web add /tmp/songxiyuan-dsh-tracebook-0.1.0.tgz

装好后打开 http://127.0.0.1:<dsh-port>/tracebook/，或直接点击会话标题栏的 Tracebook 按钮。

验证安装

dsh --profile web --dump-config | grep -A3 tracebook   # 组合后的树里有 tracebook 行
dsh web
curl -s http://127.0.0.1:<port>/tracebook/api/cases    # 同源只读 API 有响应

升级与卸载

| 安装方式 | 升级步骤 | | --- | --- | | npm | dsh plugin --profile web add @songxiyuan/dsh-tracebook@<新版本> | | 源码（link） | git pull && npm ci | | 离线 tarball | 重新 npm pack，再 dsh plugin --profile web add <新 tgz> |

dsh plugin --profile web remove @songxiyuan/dsh-tracebook

dsh.profile.bundles 里的条目会随依赖移除自动清理。Artifact 文件与 Case 数据不会被删除，需要时手动清理 artifactDirectory 与对应 storage。

排错

| 现象 | 原因 | 处理 | | --- | --- | --- | | 启动时报 DSH peer 包 ERR_MODULE_NOT_FOUND | 用了 --legacy-peer-deps，link 依赖树不完整 | 删除 node_modules 后重跑 npm ci | | dump-config 里有 tracebook 行，但页面 404 | dist/web/ 缺失 | 在仓库里 npm run build:web（或完整 npm run build） | | 页面能打开但没有样式 / 控制台加载旧资源 | 构建产物陈旧 | npm run build:web 后强制刷新 | | 会话标题栏没有 Tracebook 按钮 | dist/client.js 未生成，或改完 Client Plugin 没生效 | npm run build:client 后刷新页面（client-hmr 通常已推送新 bundle），仍不行再重启 dsh web | | dsh plugin 报 pnpm not found on PATH | 目标机器没装 pnpm | 安装 pnpm 后重试 | | 安装时 pnpm 报 Issues with peer dependencies found | 能力包由 DSH 自身安装提供，profile 里不重复装 | 可忽略：实测装完能正常启动，/tracebook/api/cases 返回 200 | | 两个 profile 各有一份数据 | artifactDirectory 用了相对路径 | 在 cordis.patch.yml 里写绝对路径 |

不推荐：直接安装 git 源

dsh plugin --profile web add github:songxiyuan/tracebook

实测失败（ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED）：git 依赖必须现场跑 prepare 重建 dist/，而 pnpm 10+ 默认拦截依赖的构建脚本；allowBuilds 的键必须是带 commit 的完整解析串，每次 push 都会变，升级时还要重配一次。用方式 1 或方式 2。

配置

Bundle 默认插入一个 tracebook Host plugin。在 ~/.dsh/profiles/web/cordis.patch.yml 里覆盖：

- id: tracebook
  config:
    artifactDirectory: /absolute/path/to/tracebook-data/artifacts
    seedExampleCase: true

Patch 按行定位：没写的字段保持原值，但 config 是整块替换而不是深合并，所以要把这一行要用的键一起列出。这里只有 id + config，不存在 update: 之类的包裹键。

| 字段 | 默认 | 用途 | | --- | --- | --- | | artifactDirectory | .tracebook/artifacts（相对工作目录） | Artifact 文件目录。多机器 / GUI 场景建议改成绝对路径，否则数据会跟着工作目录漂移 | | webDirectory | dist/index.js 同级的 dist/web/ | 自定义已构建 Viewer 目录，一般不用改 | | metadataOnlyArtifacts | false | 仅保存 Artifact 元数据、不写 payload；主要用于受限部署和测试 | | seedExampleCase | false | 启动时幂等写入一个覆盖 8 类 Block 与 5 类 Artifact 的完整 mock Case |

Storage backend 由 DSH storage-domain 路由决定，Tracebook 不直接依赖 SQLite。seedExampleCase 只在首次生效，重复启动是 no-op。

Agent Tool 示例

创建 Case：

{
  "title": "PPT 生成功能",
  "type": "exploration",
  "environment": "production",
  "sourceSessionId": "session-123"
}

增量更新：

{
  "caseId": "ppt-generation-a1b2c3d4",
  "expectedRevision": 1,
  "summary": "已确认 Page → API → Service 链路。",
  "upsertBlocks": [
    {
      "id": "backend-flow",
      "type": "flow",
      "title": "后端调用链",
      "direction": "TB",
      "nodes": [
        { "id": "page", "label": "PPT Page", "kind": "page" },
        { "id": "api", "label": "POST /slides/generate", "kind": "api" }
      ],
      "edges": [
        { "id": "page-api", "source": "page", "target": "api", "label": "CALLS" }
      ]
    }
  ]
}

读取已有 Context：

{
  "caseId": "ppt-generation-a1b2c3d4",
  "query": "callback",
  "maxBlocks": 8
}

HTTP API

Viewer 使用同源只读 API；MVP 的唯一业务写入口是 Agent Tool。

GET /tracebook/api/cases
GET /tracebook/api/cases/:id
GET /tracebook/api/cases/:id/blocks
GET /tracebook/api/cases/:id/revision
GET /tracebook/api/cases/:id/revisions
GET /tracebook/api/cases/:id/revisions/:revision
GET /tracebook/api/sessions/:sessionId/cases
GET /tracebook/api/artifacts/:id

Client Plugin

src/client/ 是很薄的一层浏览器插件，只做三件事：

在会话标题栏注册 Tracebook 按钮，打开当前 Session 的 Case（Right Sidebar，失败退化为新标签）。
在 Right Sidebar 注册 tracebook page tab，用同源 iframe 承载 Vue SPA。
监听 Viewer 的 postMessage，把 Ask about this 文本追加到当前对话草稿。

构建产物是 DSH Client Modules 期望的 lazy-CJS bundle，模块 id 即包名：

npm run build:client   # → dist/client.js + dist/client.js.map

package.json 通过 exports["./client"] 与 dsh.client 声明；宿主启动时按 profile 扫描加载。

开发

npm run typecheck
npm test
npm run build
npm run verify         # typecheck → build → test（built-viewer 测试需要 dist/web）

src/core/          领域模型、Schema、Repository、Service、HAR 匹配
src/host/          DSH Storage、Tool、HTTP、Artifact adapter
src/client/        DSH 薄 Client Plugin（入口、Tab、追问桥接）
web/src/           Vue Viewer
scripts/           Client bundle 构建
tests/             Core、HTTP 路由、HAR 匹配与构建产物测试
doc/               设计文档
docs/research/     调研与决策记录

改动生效范围：

仅改 Vue Viewer（web/）：npm run build:web 后刷新页面即可——Host 对 /tracebook 的静态资源按请求读盘。
改了 Client Plugin（src/client）：npm run build:client。web profile 默认启用 dsh-client-hmr，它轮询每个 dsh.client bundle 的 mtime/size，变化时经 /plugins/events 推给浏览器热更新；刷新页面可兜底。
改了 Host Plugin（src/host、src/core、src/index.ts）：默认必须重启 dsh web——宿主插件的主模块在启动时只 import 一次，dist/index.js 变了也不会重新加载。只刷新页面不够。

可选：打开宿主 HMR 免重启。web profile 的 base 层自带 @deepseek-ai/cordis-plugin-hmr，但默认 disabled: true。在 ~/.dsh/profiles/web/cordis.patch.yml 里打开，并把监控根目录指到插件的构建产物：

- id: hmr
  disabled: false
  config:
    root: ['.', /absolute/path/to/tracebook/dist]
    ignored: ['**/node_modules', '**/.*']
    debounce: 100

之后 npm run build 写出的新 dist/index.js 会在进程内热重载：HMR 顺着 Node 模块图清缓存，只重载依赖该文件的插件行；Agent 的工具列表每个 step 都从实时注册表重新组装，所以正在进行的会话下一步就能用上新的 Tool schema，不必新建会话。两点限制：patch 里的 config 是整块替换，必须重述 base 默认的 root: ['.']；框架级依赖的变化仍会退化成 loader.exit() 整进程重启。首次启用 HMR 这一步本身仍需要重启一次 dsh web。

完整架构与产品边界见设计方案，交互补齐的范围、落地位置与验收见交互补齐说明。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme