前言¶

在 DeepSeek Harness（DSH）里写智能体或做项目协作时，议题往往落在 Beads 工作区里，由 bd CLI 管理。终端侧已有 bv 一类查看器；若希望在不离开 Harness 界面的前提下扫列表、读详情、点文件引用，就需要把 Beads 接到客户端 UI。下面介绍社区插件 dsh-beads-viewer（维护者 Rick1125，MIT 许可证，npm 包名 dsh-beads-viewer，当前资料中版本为 1.1.4）：它在 DSH 右侧栏注册一个与「文件」并列的 beads 标签页，通过 Host 只读路由调用本机 bd，不直接读数据库文件。

这是什么¶

dsh-beads-viewer 的定位是：Beads issues in the DeepSeek Harness right sidebar — 即 Harness 浏览器端的 Beads 议题浏览器。插件分类为客户端；在插件管理器里简介为「Beads Viewer for DSH」。数据与展示分离：Host 半部提供 GET /beads-viewer/api，Client 半部负责侧栏标签、列表、筛选与 Markdown 渲染。

核心功能¶

侧栏标签与布局¶

• 在右侧栏「新建标签」引导里注册 beads 类型标签，可停靠、分屏、浮动，行为与其他页面一致；切换标签后状态保留。
• 列表行高统一（三行行框高度），长标题在容器边缘截断；悬停行有 teal 色高亮，深浅主题均可用。

列表、筛选与就绪状态¶

• 展示 bd ready 对应的 Ready 芯片，以及被未关闭阻塞项挡住的 Waiting 芯片；状态芯片带实时计数。
• 提供搜索框（按 / 可聚焦）与排序。

徽章与 Markdown¶

• 每行显示状态、优先级、类型等彩色徽章；文字颜色由填充亮度推导，保证可读性（测试要求色差 ΔE ≥ 25）。
• 内置小型 Markdown 渲染器，支持标题、嵌套与任务列表、表格、围栏代码、引用与强调；长评论线程默认展开最新评论。
• 设计说明、备注、验收标准、评论等次要块落在淡色 accent 底上，描述正文为主内容。

引用与议题 ID¶

• 文本中的项目文件路径若真实存在，可在文档预览中打开；议题 id 可打开对应议题；目标不存在时保持纯文本。
• ⧉ 复制 id，↵ 在编辑器光标处插入 id（单次可撤销编辑）。

与 Host 一致的外观与语言¶

• 跟随 Host 的文字大小、字体与界面语言（zh / en）。

安装与启用¶

先从 registry 安装，或指向本地 checkout（会将 profile 条目链接到该目录）：

# from the registry
dsh plugin --profile <name> add dsh-beads-viewer

# or from a checkout, which links the profile entry to this directory
dsh plugin --profile <name> add /path/to/dsh-beads-viewer

安装后重启 Harness，客户端 bundle 才会加载；硬刷新浏览器也可加载较新的 bundle。新标签会出现在右侧栏的 new-tab 引导中。

• 链接式安装：下次加载即反映目录内修改，无需重装。
• registry 安装：普通 npm 包，升级需再次执行 add。

依赖条件¶

1. 运行 Harness 的机器上需有 bd CLI。Host 在 PATH 及常见 Homebrew、Go 安装路径查找；brew install beads 即可满足常见 macOS 场景。
2. 当前项目需有 Beads 工作区。面板通过 bd where 解析工作区，子目录、git worktree、BEADS_DIR 覆盖与 bd 自身行为一致。

若缺其一，面板会在界面内说明原因（含 bd 返回的信息）。

Host 如何读取 tracker¶

Host 提供只读路由 GET /beads-viewer/api：

?force=1 可绕过约四秒的列表缓存。

设计要点（资料原文）：

• 通过 shell 调用 bd，不读数据库文件；工作区可能是 Dolt 或 SQLite，schema 随 bd 版本变化，bd --json 为稳定接口；需迁移时展示 bd 原文说明。
• 只读：统一经 readBd，argv 前加 bd --readonly。
• 仅本机：拒绝非 loopback 对端；?cwd= 必须是存在且（自身或父目录）含 .beads 的目录，后续所有 bd 调用限定在该工作区。

典型用法¶

1. 满足 bd 与 Beads 工作区后，按上文命令把插件加入 profile 并重启 Harness。
2. 在右侧栏新建 beads 标签，列表加载当前工作区议题；用 Ready / Waiting 与状态芯片缩小范围，必要时用搜索与排序。
3. 点开某条议题阅读 Markdown 详情；点击文中有效文件路径在预览中打开；用复制或插入快捷键把 id 带回对话编辑器。
4. 开发插件本身时，可对 checkout 做链接安装，改 client.js / index.js 后刷新即可验证。

适用场景与注意¶

适合：已在项目中用 Beads + bd 管议题，且主要工作在 DSH 内完成、希望侧栏只读浏览而非再开终端 bv 的开发者。

注意：

• 插件 Host 半部以当前 DSH 进程权限执行 bd；安装前请自行查看 GitHub 仓库 源码与 MIT 许可证。
• 社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文介绍的是社区维护的客户端插件。
• FAQ 中常见项：旧版可能出现标签 UI 在但数据 404（客户端已渲染、数据路由未注册），1.0.0 起 Host 会等待服务就绪，否则重启 Harness；字体字号不跟 Host 时硬刷新；bd 未找到则装 beads 或修正 PATH；无工作区则 bd init 或设置 BEADS_DIR；旧工作区迁移按面板显示的 bd 说明操作。

结尾¶

dsh-beads-viewer 把 Beads 议题接到 DSH 右侧栏：只读、经 bd 读 tracker，并提供列表筛选、Markdown 详情与文件/议题跳转。需要时可从 registry 或本地路径安装，并确保本机 bd 与项目 Beads 工作区就绪。

• 目录页：https://www.skillhub.cn/plugins/Rick1125/dsh-beads-viewer
• GitHub：https://github.com/Rick1125/dsh-beads-viewer