前言¶

在 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