# 海康智存（hiksemi）连接器

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

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

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

> **部署到新机器请先看 [INSTALL.md](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 固件当前版本）：

| 客户端 | 认证 | TreeConnect |
|---|---|---|
| Python `smbclient` 库 | 成功（SMB 3.1.1） | **任何共享都返回 `STATUS_ACCESS_DENIED`**，连 `IPC$` 都进不去 |
| Windows 原生 SMB | 成功 | 正常，可读写 |

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

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

## 2. 安装

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

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

手动安装：

```bash
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`：

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

| 字段 | 说明 |
|---|---|
| `host` / `port` | NAS 的 IPv4 地址，端口默认 445 |
| `username` / `password` | App 里设置的 Samba 账号。密码也可用环境变量 `HIKNAS_PASSWORD` |
| `backend` | `unc` = Windows 原生 SMB（海康用这个）；`smb` = smbclient 库 |
| `unc` | SMB 共享名。海康智存通常是 `Home1`，可用 `net view \\IP` 确认 |
| `root` | 共享内的起始目录，留空表示共享根 |
| `allowed_roots` | **建议填写**。只允许访问这些子目录，超出范围直接拒绝 |
| `max_read_bytes` | 单次读取上限，支持 `"4MB"` 写法 |
| `export_dir` | 导出到本机的目标目录 |

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

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

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

验证：

```powershell
cmdkey /list:192.168.1.100
```

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

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

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

## 5. 接入 WorkBuddy

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

```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. 可用工具

| 工具 | 作用 |
|---|---|
| `nas_status` | 检查配置与连通性、各共享根目录延迟 |
| `nas_list_dir` | 列目录，可关掉 `detail` 提速 |
| `nas_stat` | 单文件/目录的元信息 |
| `nas_search_files` | 按文件名、通配符、扩展名、修改时间、大小检索 |
| `nas_read_text` | 读纯文本正文，自动探测 UTF-8/GB18030/Big5 |
| `nas_extract_document` | 抽取 docx / xlsx / pptx / pdf 正文 |
| `nas_media_info` | 图片分辨率、MP4/MOV 时长 |
| `nas_dir_usage` | 目录容量摸底：总量、扩展名占比、最大文件排行 |
| `nas_export_files` | 导出到本机，保留相对目录结构 |

路径写法两种：`审计资料/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`，它会直接给结论。

**连不上：**

| 现象 | 处理 |
|---|---|
| `ping` 不通 | 电脑与 NAS 不在同一局域网 |
| 认证失败 | Samba 账号密码错，或该账号没有此共享的读权限 |
| 路径不存在 | 共享名写错，或目录名大小写不符 |
| `backend: unc` 报登录失败 | 凭据未写入，执行第 4 节的 `cmdkey` |
| `backend: smb` 报 `STATUS_ACCESS_DENIED` | 海康的 Samba 不兼容 smbclient，改用 `backend: unc` |

## 9. 测试

```bash
# 离线单测，不需要 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
```

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

```bash
.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](LICENSE)。

## 免责与合规

- 工具本身只读，不提供任何写入 NAS 的接口；但**读取数据的行为仍受法律与单位制度约束**。在单位设备、他人存储或涉密环境中使用前，请确认你已取得相应授权。
- 仓库中的文档示例（`192.168.1.100`、`<账号>`、`<密码>`）均为占位符，不含任何真实凭据。`config.json` 已被 `.gitignore` 排除，请勿提交自己的配置文件。
- 导出功能会把文件复制到本机，导出目录同样可能包含敏感内容，注意清理。
- WorkBuddy、海康智存 / hiksemi 等名称归各自权利人所有。本项目为独立开发的第三方工具，与海康威视及其关联公司**无隶属、代理或背书关系**，"兼容"仅指在自购设备上实测可用。