海康智存（hiksemi）连接器

让 WorkBuddy 通过局域网 SMB 读取海康智存 NAS 上的文件，用于资料检索、内容分析和归档摸底。

严格只读：连接器不提供写入、改名、删除 NAS 文件的任何工具。唯一会写磁盘的动作是把文件导出到本机。

当前状态：已在真机验证。共享 Home1，12 个根目录可正常读取，检索、文档抽取、容量统计均已实测通过。

部署到新机器请先看 INSTALL.md —— 面向新环境的完整安装步骤、配置说明、排查手册。 一键安装：python install.py。本文档侧重原理与开发细节。

1. 前置条件

海康智存属于消费级/中小企业私有云产品线（H99、H200、N100、T1 等型号），没有公开的开放 API，所以走它自带的 Samba 服务：

1. 手机打开「海康智存」App → 进入你的设备

2. 「局域网应用」→ 打开 Samba

3. 设置专用账号和密码，并把「访问路径设置」限定到需要的目录——不要直接用管理员账号开整个存储

4. 记下设备 IPv4 地址

5. 在路由器里给 NAS 做 DHCP 地址保留，避免 IP 变动后连接失效

只建议在同一局域网内使用。海康智存的云端（cloud.hiksemi.cn）走的是私有协议，无文档且随客户端版本变化，本连接器不依赖它。

注意：海康的 Samba 与 smbclient 库不兼容

实测结论（2026-11，NAS 固件当前版本）：

错误密码在两种客户端下都会正确返回 STATUS_LOGON_FAILURE，说明认证链路本身没问题，是海康的 Samba 在 TreeConnect 阶段拒绝了第三方客户端的请求。

因此本连接器默认使用 Windows 原生 SMB 栈（配置里 backend: "unc"），通过 \\host\share\... 路径访问，绕开这个兼容性问题。backend: "smb" 保留给其他厂商的 NAS 使用。

Related MCP server: sync2nas-mcp

2. 安装

推荐一条命令（只依赖标准库，会建 venv、装依赖、写配置、存凭据、注册 MCP、跑自检）：

python install.py --host 192.168.1.100 --username <账号> --password <密码> --share Home1

手动安装：

python -m venv .venv
.venv/Scripts/python.exe -m pip install -i https://pypi.org/simple -r requirements.txt

国内镜像源（清华）可能缺 mcp 包，装依赖时指定官方源 -i https://pypi.org/simple。

3. 配置

把 config.example.json 复制为 config.json：

{
  "host": "192.168.1.100",
  "username": "你的 Samba 账号",
  "password": "你的 Samba 密码",
  "backend": "unc",
  "default_share": "home",
  "shares": [
    { "name": "home", "unc": "Home1", "root": "", "allowed_roots": [] }
  ]
}

4. 存储凭据（backend: unc 必做）

Windows 原生 SMB 走系统凭据，Python 进程读不到 config.json 里的密码。需要把凭据存进 Windows 凭据管理器，一条命令：

cmdkey /add:<NAS_IP> /user:<账号> /pass:<密码>

验证：

cmdkey /list:192.168.1.100

或临时用（重启后失效）：

net use \\<NAS_IP>\Home1 /user:<账号> <密码>

本项目已执行 cmdkey，凭据已持久化。换 NAS 或改密码后要重新执行。 删除旧凭据：cmdkey /delete:192.168.1.100

5. 接入 WorkBuddy

连接器通过 MCP 协议接进 WorkBuddy。编辑 ~/.workbuddy/mcp.json：

{
  "mcpServers": {
    "hikvision-nas": {
      "command": "C:/Users/hzp/WorkBuddy/2026-11-09-12-29-54/hikvision-nas-connector/.venv/Scripts/python.exe",
      "args": ["C:/Users/hzp/WorkBuddy/2026-11-09-12-29-54/hikvision-nas-connector/src/server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

保存后，到「连接器」管理页右上角的「自定义连接器」入口点击 信任，新服务器才会启用。

改完 config.json 不需要重启服务，下次调用会自动重载。

6. 可用工具

路径写法两种：审计资料/2024/a.docx（走默认共享），home:/审计资料/2024/a.docx（指定共享）。

7. 已知限制

• 老的 .doc / .xls / .ppt 二进制格式无法抽取正文，会提示先另存为新格式或导出到本地处理。

• 单个文件超过 32MB 时不做正文抽取（PDF/Office 必须整份读入，截断只会得到误导性的"文件损坏"），会提示先导出。

• 视频只对 MP4/MOV 容器能读时长和分辨率，AVI/MKV 等只能给文件大小。

• 递归检索是串行的，大目录较慢，受 max_scan_entries（默认 2 万条）约束；返回里的 scan_truncated 标明是否没扫完。

• 共享名和目录名区分大小写。

• backend: unc 仅 Windows 可用；换 Linux/macOS 需改回 smb 并自备兼容的 Samba。

8. 排查

先调 nas_status，它会直接给结论。

连不上：

9. 测试

# 离线单测，不需要 NAS（40 项）
.venv/Scripts/python.exe tests/selftest.py

# 业务逻辑，内存虚拟文件系统（44 项）
.venv/Scripts/python.exe tests/mock_smb.py

# MCP 协议层，模拟 WorkBuddy 拉起进程（9 项）
.venv/Scripts/python.exe tests/mcp_smoke.py

# 真实 NAS 端到端（需要连通与凭据）
.venv/Scripts/python.exe tests/mcp_live.py

诊断工具（连接异常时用）：

.venv/Scripts/python.exe tests/probe.py <账号> <密码>   # 认证与共享名
.venv/Scripts/python.exe tests/raw_smb.py                    # 裸 SMB 协商包
.venv/Scripts/python.exe tests/scan_ports.py                 # 端口与服务

许可证

MIT。

免责与合规

• 工具本身只读，不提供任何写入 NAS 的接口；但读取数据的行为仍受法律与单位制度约束。在单位设备、他人存储或涉密环境中使用前，请确认你已取得相应授权。

• 仓库中的文档示例（192.168.1.100、<账号>、<密码>）均为占位符，不含任何真实凭据。config.json 已被 .gitignore 排除，请勿提交自己的配置文件。

• 导出功能会把文件复制到本机，导出目录同样可能包含敏感内容，注意清理。

• WorkBuddy、海康智存 / hiksemi 等名称归各自权利人所有。本项目为独立开发的第三方工具，与海康威视及其关联公司无隶属、代理或背书关系，"兼容"仅指在自购设备上实测可用。