dsh-yingnao：讓智能體治理本地磁盤

前言¶

DeepSeek Harness (DSH) 的核心理念是「一切皆插件」，通過擴展工具鏈賦予智能體多樣化的能力。在本地文件管理與數據治理場景下，現有的通用插件往往難以直接操作磁盤，或者缺乏對本地數據結構的深層語義理解。

dsh-yingnao 是一個由 qiuyiwu1989-star 維護的 DSH 插件，它將本地磁盤的索引能力引入 Harness。它的核心價值在於讓智能體不僅能「看」到本地數據，還能通過語義搜索發現隱藏的關聯，並分發治理任務。該插件使用 MIT 許可證，無需 API 密鑰即可管理本地機器。

核心功能¶

該插件主要提供以下能力：

索引本地磁盤：通過本地運行的 Yingnao 服務建立文件索引，文件本身不移動，僅索引數據進入數據庫。
查看磁盤黑暗區域：智能體可以查看磁盤上未被索引或未處理的空間，評估治理進度。
搜索文件：支持基於名稱、路徑或內容的文件檢索。
查找語義鄰居：通過語義相似性，從已知文件找到相關的其他文件，這比單純的文本搜索更高效。
分發治理任務：智能體可以將文件清理、格式化等任務分發給本地服務執行。

安裝與啓用¶

安裝過程需要執行官方提供的命令，且必須在本地啓動 Yingnao 服務。

安裝插件：
使用以下命令將插件添加到 DSH：

    npx -p @deepseek-ai/dsh dsh plugin --profile web add github:qiuyiwu1989-star/dsh-yingnao

構建輸出隨倉庫打包，無需額外構建腳本權限。安裝後需重啓 profile。

啓動 Yingnao：
插件默認連接 http://127.0.0.1:5050。需在本地運行 Yingnao 索引服務（桌面客戶端會自動處理，或直接運行 python3 app.py）。

典型用法¶

安裝並運行後，智能體可以調用以下工具：

yingnao_overview：
在執行任何治理前，先查看磁盤狀態。瞭解還有多少空間是「黑暗」的（未索引），以及已處理數據的質量。
yingnao_search：
查找文件。當需要定位特定文件或路徑時使用。它會退化而非失敗，即使文件沒有可提取文本，也會基於名稱和路徑進行匹配。
yingnao_related：
找到語義相關文件。當智能體手中有一個錨點文件（例如一份草稿），使用此工具向外擴散，尋找語義上的鄰居。這能幫助智能體發現從未主動搜索過的相關素材。
yingnao_govern：
分發治理任務。這是插件的手，用於執行清理或規範化操作。

治理邊界與配置¶

在使用 yingnao_govern 時，需要明確其邊界。

治理操作的邊界¶

並非所有操作都由智能體直接執行。以下兩類操作不能由智能體決定執行：
* 涉及金錢的操作（如 OCR 重新提取、LLM 標註）。
* 移動真實文件的操作（如收件箱歸檔）。

對於上述操作，Yingnao 會標記 needs_confirm。智能體只能將其加入隊列，等待用戶在桌面客戶端中確認後纔會執行。

除此之外的操作（如質量檢查、字符規範化）是可逆的，且會立即執行。

配置項¶

可以通過 YAML 配置文件控制插件行爲：

- insert:
    - id: yingnao
      name: 'dsh-yingnao'
      config:
        endpoint: 'http://127.0.0.1:5050'
        timeoutMs: 60000
        passthrough: true
        allowGovern: true

endpoint：Yingnao 的本地索引服務地址。
timeoutMs：查詢超時時間（默認 60000ms），用於處理跨 SSH 隧道的慢速請求。
passthrough：是否註冊 yingnao_call（出口通道）。
allowGovern：是否允許執行治理任務。設爲 false 時，yingnao_govern 退化爲只讀模式。

此外，也可以通過環境變量 YINGNAO_ENDPOINT 覆蓋配置文件中的地址。

錯誤分類¶

插件將錯誤分類以便智能體調整行爲，而非返回堆棧信息：

錯誤類型	智能體應採取的行動
`offline`	Yingnao 未運行。不要重試，應提示用戶啓動服務。
`tunnel`	服務在線但無法連接數據庫。可能恢復，稍後重試一次。
`notfound`	找不到指定資源。應修改參數，不要直接重試。
`server`	服務端異常。重試一次，若持續失敗則提示用戶。

生態配對¶

該插件常與 dsh-deepbrain 配對使用。前者提供基於證據鏈的判斷，後者提供原始素材的來源。通過組合兩者，智能體既能基於過往決策生成內容，又能追溯這些決策所依據的具體本地文件。

總結¶

dsh-yingnao 解決了本地文件治理的自動化問題。它通過語義索引和受控的治理任務接口，讓智能體在不越權移動文件或消耗資源的情況下，有效地管理本地數據。對於需要本地化、隱私保護的數據處理流程，這是一個必要的工具。

目錄頁：https://www.skillhub.cn/plugins/qiuyiwu1989-star/dsh-yingnao
源碼倉庫：https://github.com/qiuyiwu1989-star/dsh-yingnao