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