工作区检查器 kk-ai-lab/dsh-workshpace-plugin

DSH 工作区插件

DSH 工作区在本地 DeepSeek Harness Web UI 中添加了一个 Workspace 标签页。它让你可以查看 agent 触碰过的内容、查看只读的 Sub-agent Trace 条目、查看会话产物、预览有界内容、检查 Git 变更、管理受管控的本地工作区记忆，以及查看 Agent 创建的 Memory 提案——所有这些都无需离开对话。

它的用途

Harness 会话在 agent 工作时可能会产生有用的文件和状态，但这些信息不应占据聊天布局。此插件让工作区体验保持紧凑且感知会话：

- 在对话视图行中 Trajectory 旁边的一个 Workspace 标签页（唯一的入口）；
- 在现有工作区标签页上方的一个只读 Sub-agent Trace，带有有界后代树和所选子项详情；
- 工作区标签页顶部的一个会话摘要块，显示 agent 触碰过的内容（按类型分类的文件、产物、记忆/决策计数、活动 span）——按需派生，因此对实时会话和重新打开的会话表现一致；
- 标签式界面：Artifacts、Memory 和 Git 采用共享的视觉系统（自动刷新、友好的空/错误状态、可键盘操作）；Git 标签页承载 Changes 和 History 视图；
- 产物预览（按类型分组、可搜索，每项显示大小 · 修改时间 · 状态，并支持一键下载、复制路径），包括只读多标签预览、可渲染相对图片和 mermaid 图表的 markdown 预览，以及流式 PDF 预览；记忆治理控件和可读的 Git 检查都保留在这些界面内；
- 记忆按会话自动写入为派生事实，因此 Export 会携带有用的信息；
- Git：仓库状态头部（分支、脏/干净、已暂存 / 未暂存 / 未跟踪计数、领先/落后），Changes 分组为已暂存 / 未暂存 / 未跟踪部分，带有可过滤状态和可读的统一/拆分差异，以及提交 History（提交列表 + 每个提交的文件/差异）；非 Git 工作区显示干净的“不是 Git 仓库”状态；
- 这些界面使用作用域样式，因此不会全局改变 Harness 外壳；
- 所有显示的文案均提供英文和中文，并遵循 Harness 应用语言（浏览器语言仅作为回退）。

安装插件

从此仓库构建插件：

npm install
npm run build

将构建好的插件注册到本地 Harness 检出。在 Harness 项目目录中运行此命令，或调整相对路径以指向此仓库的检出位置：

dsh plugin --profile web add ../dsh-workshpace-plugin

该命令将 Web 插件注册存储在本地 Harness 配置文件中。

启动 Web UI

dsh web

在浏览器中打开 http://127.0.0.1:3080/。重新构建插件后请重启 Web UI，以便加载最新的 bundle。
对于源码变更，请运行 npm run build，停止当前的 dsh web 进程，然后再次启动 dsh web。仅当插件注册或链接路径发生变化时，才需要重新运行 dsh plugin --profile web add ...；重新构建已链接的插件只需重启 Web 即可。

使用工作区

1. 打开 Harness Web UI 并选择一个模型。
2. 选择或创建一个由工作区支持的会话。
3. 开始对话，让 agent 创建或检查文件。
4. 打开 Workspace 会话标签页。
5. 检查标签页上方的 Sub-agent Trace，以跟踪本地由会话支持的子 Agent；不可用或损坏的子项仍会带有标签，而不会显示为空。
6. 使用这些标签页：
- Artifacts — 检查会话创建的交付物（按类型分组，可按名称搜索），列表旁带有有界预览，每项显示大小 · 修改时间 · 预览状态、复制路径以及一键下载；
- Memory — 查看、创建、验证、固定、归档或遗忘项目/会话 Memory 记录，查看 Agent 提议（model-suggested 项在您验证或拒绝之前显示为未验证），并查看自动写入器从 agent 活动中推导出的会话事实；
- Git — 仓库状态头部（分支 + 短 head、脏/干净、已暂存 / 未暂存 / 未跟踪计数、领先/落后），然后是 Changes / History 切换：Changes 显示工作树和已暂存的更改（自动刷新，分为已暂存 / 未暂存 / 未跟踪部分，可按状态筛选），带有彩色、带行号的统一 diff、+N −M 统计以及复制 diff 控件；History 显示提交列表以及每个提交的文件/diff 详情。

Workspace 标签页以基于卡片的布局和限定作用域的样式渲染这三个界面；标签页上方的摘要块跟踪相同的会话事实。

在本地开发和验证

npm test
npm run check
npm run build
npm run smoke:compat

npm run build 将可运行的包 bundle 写入 lib/。当插件注册后，Web 配置文件会加载该 bundle。构建还会将 mermaid vendor bundle 复制到 lib/assets/，以便宿主能够以同源方式提供图表。

故障排除

- Workspace 标签页缺失： 重新构建插件，重启 dsh web，如果本地配置文件是在构建之前创建的，则再次添加插件。
- 旧的浮动面板仍然可见： 一个较旧的 Web 进程正在提供缓存的 bundle；停止它并再次运行 npx @deepseek-ai/dsh web。冗余的右下角胶囊按钮已在 v0.2 中移除——Workspace 标签页是唯一入口。
- 在 v0.6 之前创建的历史会话将无法重新打开： v0.6 之前的版本将自定义的 workspace/summary 事件持久化到会话日志中，而 DSH 的冷持久化路径拒绝加载包含未知不可忽略事件类型的日志。v0.6 停止持久化该事件，因此新会话是干净的并可正常重新打开；已受影响的日志无法安全重写（seq 连续性），因此这些特定会话无法恢复——请删除它们或启动新会话。
- Markdown 图片或 mermaid 图表不显示： 插件通过同源不透明资源路由和供应商 bundle 提供它们；如果 Web UI 是在 v0.6 重新构建之前启动的，请重启 dsh web，以便注册新路由（/workspace/vendor/mermaid.js、/workspace/resource 上的 Range/ETag）。
- Artifacts 或 Memory 为空： 从活动的 Harness 会话打开 Workspace；这些界面读取的是会话范围内的数据，而不是全局文件列表。
- Git 显示“not a Git repository”： 工作区根目录不是 Git 检出目录。请从工作目录为 Git 仓库的会话打开 Workspace，以查看 Changes 和 History。
- Memory Export 下载空 bundle（"records":[]）： 仅当会话没有 Memory 且没有 agent 文件活动时，这才是预期行为。自 v0.2 起，会话自动写入器会从 agent 工具活动（按类型划分的文件 + artifacts）中派生 fact 记录，因此即使没有手动记录，活动会话也会导出有用的事实。手动记录在 UI 中创建，或由 Agent 通过 workspace_memory_propose 提议；在你 Verify 之前，提议会以 unverified 状态存储。存储详情：docs/MEMORY_STORAGE.md。
- 命令找不到插件： 请从 Harness 项目运行 add 命令，并使用指向此仓库的正确相对路径。

项目术语定义在 CONTEXT.md 中，架构决策记录在 docs/adr/ 中。产品/架构文档：docs/DSH_Workspace_PRD.md 和 docs/DSH_Workspace_ARD.md。