# 工具安装、环境确认与修复手册

本手册用于同事首次部署、迁移电脑以及处理具体工具调用故障。与 [团队部署](team-setup.md)、[工具路由](tool-routing.md)、[有界 CLI](cli-tools.md) 配合使用。这里只分发通用方法、配置格式和已验证的修复经验；工具程序、驱动、私人运行环境、凭据和现场证据由各机器自行准备。

已授权安装或修复当前用例所需工具时，可按下面流程继续，不必逐步重复审批。先复用可用安装；只处理当前必需的缺口，不因工具清单中有某项就安装整套软件。系统管理员权限、许可证、下载权限和人工登录仍按本机及产品要求处理。安装器、驱动安装、服务重载和设备操作不能混成一次“doctor 自动修复”。

## 1. 先确定故障在哪一层

| 层次 | 检查与记录 | 不能据此推出的结论 |
| --- | --- | --- |
| 包与文件 | 来源、包摘要、可执行文件/解释器/DLL 的实际路径 | 有 ZIP、安装 EXE 或文件名就表示已安装 |
| 运行时 | 版本/帮助能运行，DLL 或 Python 模块能加载 | 工具已能连接目标设备 |
| 本地功能 | 人造媒体、签名样本、已有脱敏抓包能解析 | 真机媒体质量或安全用例通过 |
| 连接与会话 | 当前网卡/COM、Android 设备、MCP、GUI、网站会话可用 | 已登录、目标权限充分或设备身份一致 |
| 业务 | 当前用例的实际动作、独立断言与证据 | 启动成功、退出码 0、任务完成就等于 PASS |

按最早失败的层次修复，再复测同一层。没有证据定位原因时保留错误和待查项，不通过改超时、重复安装或切换整套环境掩盖问题。`manual-interface` 表示要走真实 GUI/网页；`mcp-check-required` 表示要检查 MCP，它们都不是“缺少 EXE”。

以下版本是打包前的兼容性验证记录，**不是要求团队一律安装这些旧版本，也不是最新版推荐**。更换版本后须在本机复测相应能力。

| 工具/环境 | 已验证范围 | 尚未覆盖 |
| --- | --- | --- |
| FFmpeg/ffprobe，2023-12-18 构建 | 本地 1 秒、160×120、5 帧样本生成/解析/解码；另有原流 RTSP 元数据读取 | 连续码率、GOP、画音质量和其他格式 |
| Wireshark/TShark/dumpcap 4.6.3，Npcap 1.72 | 版本、接口枚举、一次有界采集及离线解析 | 新机器驱动安装、GUI 操作、完整通信安全断言 |
| Nmap 7.60 | 帮助、版本及本机单端口 TCP connect 调用 | 全端口、UDP、服务身份及设备安全结论 |
| Binwalk 2.3.2＋独立 Python 3.11 | 正式 `firmware-scan` 识别人造 gzip 签名；真实固件扫描完成但未检出签名 | 真实固件完整分析、提取器依赖、解包与加密验收 |
| MediaInfoLib 21.09＋匹配位数的 Python | 正式 `media-info` 解析本地样本；在两种 Python 运行环境复测 | GUI、所有格式或操作系统级断网隔离 |
| PowerShell 串口采集 | 明确参数下的被动收取；单独现场诊断曾确认基础双向收发 | 通用自动登录、shell 命令、SecureCRT GUI 全流程 |
| 配置工具 V2.0.5 | 包与实际 EXE 一致、启动、版本控件读取；独立适配器只读身份查询 | GUI 搜索、参数设置和升级全流程 |
| mainThread | 包获取、完整解压、启动与查询入口识别 | 查询权限、周期数据/拓扑返回及原用例“杭研软件”对应关系 |
| Artemis 1.5.2＋观察修复补丁 | 真实只读观察、笔记复核和正常结算 | 全部手机业务；不能把此前源码全套检查描述为全绿 |

## 2. 目录、安装器与解压

示例均使用团队占位目录，须替换为本机位置：`D:/TeamTools` 放工具，`D:/TeamConfig` 放私有配置，`D:/TeamEvidence` 放本机结果。Skill 根目录保持独立。不要将其他同事的 venv、MCP 配置、设备资料、登录会话或历史输出目录整个复制过来。

1. 核对当前已有安装的实际路径和版本，避免只看压缩包名称。记录包的 `Get-FileHash -Algorithm SHA256`；有供应方可信摘要或签名时核对来源，只有自行计算的摘要不能证明供应方真实性。
2. 对 ZIP/7z 先查看成员，确认预期入口、依赖目录及体积；不接受逃逸目标目录的绝对路径、`..` 或不明链接。解压到新的版本目录，保留旧版本。不要只取单个 EXE，Qt 插件、DLL、配置及资源目录通常需要一起保留。
3. ZIP 使用 `Expand-Archive`；7z 使用已安装且可信的 7-Zip。示例目标目录应尚不存在，避免覆盖现有环境：

   ```powershell
   Get-FileHash -LiteralPath 'D:/TeamTools/packages/tool.zip' -Algorithm SHA256
   Expand-Archive -LiteralPath 'D:/TeamTools/packages/tool.zip' -DestinationPath 'D:/TeamTools/portable/tool-version'
   & 'D:/TeamTools/7-Zip/7z.exe' l 'D:/TeamTools/packages/tool.7z'
   & 'D:/TeamTools/7-Zip/7z.exe' x 'D:/TeamTools/packages/tool.7z' '-oD:/TeamTools/portable/tool-version'
   ```

4. 必须安装的产品使用供应方正式安装器；参数按该版本说明，不猜静默开关。Windows UAC 和许可证由具备权限的使用者处理。不要运行压缩包中的激活器、破解程序或与当前工具无关的安装器。
5. 将最终执行路径写入本机 profile，再进行版本和本地样本检查。`--tool-root` 不会解压包，安装器也不能填成 `tools` 的运行入口。

上面的解压命令是部署模板，不是已在每个团队工具包上执行过的安装记录。默认不改全局 PATH；显式 profile 更容易复核实际用了哪个版本。

## 3. 基础 Python、PowerShell 与 profile

轻量脚本使用 Python 3.10+ 标准库；Binwalk 2.3.2 另用 Python 3.11；Artemis 1.5.2 的项目要求是 Python 3.12+，由其自身 `.venv` 管理。这三者可以共存，不为修复一个工具降级 Artemis 的解释器。

从 Skill 根目录检查，`python` 可替换为本机绝对解释器路径：

```powershell
python -c "import sys, struct; print(sys.version); print(struct.calcsize('P') * 8)"
python -X utf8 scripts/tool_runner.py --help
python -X utf8 scripts/tool_runner.py --tool-root 'D:/TeamTools' list
python -X utf8 scripts/tool_runner.py --profile 'D:/TeamConfig/tools.local.json' doctor
python -X utf8 scripts/tool_runner.py --profile 'D:/TeamConfig/tools.local.json' doctor --check-versions
```

`doctor` 只发现路径；`--check-versions` 才实际运行已定位程序的版本/帮助或加载检查。盘点整体退出0也可能仍有缺项，逐工具核对 availability 和 version_check，再跑对应本地样本。`--profile`、`--tool-root`、`--timeout`、`--dry-run` 放在子命令前。参照 [CLI 配置](cli-tools.md#配置与盘点) 填写 `tools`、`runtimes.binwalk_python` 和 `libraries.mediainfo`；路径可以相对 profile 所在目录，不接受命令串或额外参数。

PowerShell 已验证 Windows PowerShell 5.1 和 PowerShell 7 的基础串口类型。若 5.1 报自带 `Get-FileHash` 无法自动加载，先检查模块是否存在；历史案例通过显式导入其自带模块恢复：

```powershell
Import-Module Microsoft.PowerShell.Utility
Import-Module Microsoft.PowerShell.Security
Get-Command Get-FileHash
```

这只处理相同模块加载问题，不解决 COM 驱动或端口占用。脚本执行策略阻止运行时按组织策略解决，不能自动改为绕过策略。中文 Skill 校验遇到 GBK 解码失败时使用 `python -X utf8`，不改文档为本机编码。

## 4. FFmpeg / ffprobe：先用本地样本

从批准来源取得匹配 Windows 架构的完整构建，解压后在 profile 分别配置 `ffmpeg.exe`、`ffprobe.exe`。如果包名和 `-version` 不一致，以实际调用输出为准；原资料中的“ffmg”尚未最终确认，只将 FFmpeg/ffprobe 标为已采用的可比能力。

下列命令重用已成功的方法，生成无设备信息的样本。先创建本机证据目录；输出必须是新文件，`-n` 不覆盖已有文件：

```powershell
& 'D:/TeamTools/ffmpeg/bin/ffmpeg.exe' -nostdin -n -hide_banner -f lavfi -i 'testsrc=size=160x120:rate=5' -t 1 -c:v mpeg4 -pix_fmt yuv420p 'D:/TeamEvidence/local-video-sample.mp4'
python -X utf8 scripts/tool_runner.py --profile 'D:/TeamConfig/tools.local.json' probe --input 'D:/TeamEvidence/local-video-sample.mp4'
& 'D:/TeamTools/ffmpeg/bin/ffmpeg.exe' -nostdin -hide_banner -i 'D:/TeamEvidence/local-video-sample.mp4' -f null -
```

检查生成成功、实际尺寸 160×120、帧率 5/1、约 1 秒及解码 5 帧。失败时依次核对执行路径、DLL/构建依赖、输入文件和输出权限。RTSP 阶段另需当前明确的流地址和权限；用 `probe --rtsp-env <变量名>`，不要把认证 URL 放进 profile、聊天或报告。元数据正常之后再按用例获取帧级与持续测量证据。

## 5. Wireshark / TShark / dumpcap 与 Npcap

保留 Wireshark 完整目录，将 `tshark.exe` 和 `dumpcap.exe` 分别配置到 profile。读取已有 pcap 与现场捕获是不同能力：TShark 能离线分析不证明 Npcap 已安装，dumpcap 能显示版本不证明当前账户能抓包。

```powershell
& 'D:/TeamTools/Wireshark/tshark.exe' --version
& 'D:/TeamTools/Wireshark/dumpcap.exe' -D
Get-Service -Name npcap -ErrorAction SilentlyContinue
python -X utf8 scripts/tool_runner.py --profile 'D:/TeamConfig/tools.local.json' analyze-pcap --input 'D:/TeamEvidence/sample.pcapng'
```

无接口或加载驱动失败时，先区分程序依赖、Npcap 驱动、服务状态和当前账户权限。使用已批准的 Wireshark/Npcap 安装器按产品说明安装或修复驱动；不要把 ZIP 解压当作驱动安装，不盲装旧 WinPcap，也不因 Nmap 包带驱动而覆盖当前可用 Npcap。管理员专用访问策略按组织要求处理。

历史机器在 Npcap 1.72 下完成接口枚举和有界采集，但没有验证一套通用于所有机器的无人值守驱动安装流程。修复后先重查接口，再对当前授权的单个目标、指定接口做短时 `capture`，随后 `analyze-pcap` 回读。接口编号可能变化，不能照抄其他机器的编号；空抓包可能是接口、采集位置、过滤条件或时间窗问题，不能直接判断设备没有通信。

运行器固定 `snaplen=256`，现场采集最多 600 秒、100 MiB。只抓到截断包不够做完整应用负载或所有安全断言；扩大取证范围应回到具体用例设计。

Nmap 使用实际 `nmap.exe` 的 `--version` 检查运行时。现有 `scan` 只支持单个明确 IP、最多 128 个明确 TCP 端口的 connect 扫描；不要为环境验证扫描整个局域网。安装包版本不能代替执行版本，端口聚合或超时仍需检查覆盖度。

## 6. Binwalk：固定 Python 3.11 的隔离环境

已验证的 2.3.2 源码使用 `imp`，直接放到 Python 3.12+ 会失败。仅解压源码也可能因缺少发行元数据而无法显示版本。正确方向是在独立 Python 3.11 venv 内安装已核验的源码，profile 指向该 venv 的 Python，而非改全局 Python 或设置全局 `PYTHONPATH`。

```powershell
& 'D:/TeamTools/Python311/python.exe' -m venv 'D:/TeamTools/binwalk-env'
& 'D:/TeamTools/binwalk-env/Scripts/python.exe' -m pip --version
```

新 venv 目录应尚不存在。团队可以从批准的离线 wheel 仓库准备构建依赖后安装已审核源码；这条 pip 路径是可复用部署方案，须在本机验证：

```powershell
& 'D:/TeamTools/binwalk-env/Scripts/python.exe' -m pip install --no-index --find-links 'D:/TeamTools/packages/wheels' setuptools wheel
& 'D:/TeamTools/binwalk-env/Scripts/python.exe' -m pip install --no-index --no-build-isolation --no-deps 'D:/TeamTools/sources/binwalk-2.3.2'
```

历史修复中离线 pip 因缺 `bdist_wheel` 失败，最终在检查过源码后用该源码的 `setup.py install` 安装到同一隔离 venv，正式命令复测成功。若必须复现这条兼容路径，只在准确的 2.3.2 源码目录内执行，安装代码仍须可信；不要自动运行外层包附带的其他 Python 安装器：

```powershell
Push-Location 'D:/TeamTools/sources/binwalk-2.3.2'
try {
    & 'D:/TeamTools/binwalk-env/Scripts/python.exe' setup.py install
} finally {
    Pop-Location
}
```

配置 `runtimes.binwalk_python` 为 `D:/TeamTools/binwalk-env/Scripts/python.exe` 后，用 runner 的 `doctor --check-versions` 与 `firmware-scan --input <本地签名样本>` 复测。正式入口固定为 `python -I -m binwalk`；运行器另设临时用户配置目录，避免加载现有用户插件。不要复制历史临时补元数据目录，也不要以 Python 文件存在就认定模块可用。

此处只解决签名扫描。未准备外部提取器时标记相关能力缺失，不添加 `-e` 或执行扫描产物。解包失败、高熵或找不到字符串都不能证明设备 Flash 已加密；`firmware_encrypt` 必须另取匹配 SDK 的专用程序。

## 7. MediaInfo：Python 位数、DLL 与固定接口

从已批准的 MediaInfo 包保留 DLL 及必要依赖，在 `libraries.mediainfo` 填写实际 `MediaInfo.dll` 路径。位数匹配对象是**运行 tool_runner 的 Python 进程**，仅知道 Windows 是 64 位不够。

```powershell
python -c "import struct; print(struct.calcsize('P') * 8)"
python -X utf8 scripts/tool_runner.py --profile 'D:/TeamConfig/tools.local.json' doctor --check-versions
python -X utf8 scripts/tool_runner.py --profile 'D:/TeamConfig/tools.local.json' media-info --input 'D:/TeamEvidence/local-video-sample.mp4'
```

DLL 已找到但加载失败时检查 32/64 位、缺失依赖、文件来源与版本；不要改成调用 MediaInfo GUI 或任意复制 DLL 到系统目录来掩盖失败。正式命令在有时限子进程内调用固定 API，已验证 21.09 的样本结果为 160×120、5 帧、5 fps、1000 ms；Duration 单位是毫秒，ffprobe 通常是秒。

21.09 中 `Internet="No"` 会启用该选项。分发脚本已改为设置空字符串并回读 `Internet_Get` 确认关闭，同时拒绝直接 URL/UNC 输入。不要改回 `No`，也不要绕过此校验；无法确认时保留失败。该 DLL 配置不是操作系统级网络隔离的证明。

## 8. SecureCRT、串口驱动与无数据排查

SecureCRT 使用合法可用的原产品。只需被动日志时可采用已封装的 PowerShell 路径，无须为它安装 pySerial。USB 转串口驱动按实际转接器硬件 ID、供应方和系统架构选用；不要猜测为 CH340、CP210x 或其他型号。

```powershell
[System.IO.Ports.SerialPort]::GetPortNames()
Get-CimInstance Win32_SerialPort | Select-Object DeviceID, Name, PNPDeviceID
```

记录本机 COM 和驱动状态，确认供电、电平、共地、TX/RX、波特率和流控与现场已正常会话一致。运行器使用 8N1、无流控，默认 DTR/RTS 关闭；输出同时保存时间戳文本及 `.raw.bin`，路径必须为新文件。端口被 SecureCRT 或其他任务占用时保留占用结果，由当前持有者正常释放，不能抢占。

无数据时先核对连接和设备输出条件。历史现场按已确认的终端会话显式启用 DTR/RTS 后收到数据，但不能认定控制线是唯一原因，也不能把它设为所有设备默认值。确实需要且已确认其电气含义时才在 `serial` 命令加入 `--dtr-enable` / `--rts-enable`；它们不是硬件握手选项，部分设备用控制线复位。`profile.serial` 仅供环境记录，不会隐式改变运行器参数。

端口打开、收到日志、双向字符收发、认证成功和可用 shell 分别验收。历史一次诊断观察到用户名后返回密码提示，但没有确认 shell；通用 Skill 因而仍只提供被动采集，不包含自动登录或任意命令发送。不得将该现场诊断脚本及其目标参数复制为团队默认工具，也不循环猜测凭据。

## 9. 内部配置工具 V2.0.5、mainThread 与 GUI 宿主

配置工具按内部正式来源取得 V2.0.5 完整包，验证实际 EXE 与包内文件一致。保留 Qt/DLL/资源目录，在窗口版本控件复核 `V2.0.5 Build:2026041414`，避免误启旧版本。程序启动及控件可见已验证；独立 `device_adapter.py info` 的只读身份结果不经过 GUI，不能作为 GUI 设备发现成功证据。参数配置仍走实际界面或已验证协议，不能猜测视频参数命令。

mainThread 为实际“端侧数据采集工具.exe”的 PyQt 原生程序。通过内部授权的分发渠道取包和手册，登录下载由使用者完成；完整解压并验证能显示主菜单。未签名或无文件版本时只能记录事实，归档 CRC/SHA256 不能代替供应方身份核验。

只读入口为“进入查询端侧数据采集功能”，可查询周期数据、拓扑和已有日志地址。实际控件定位参见 [工具路由](tool-routing.md)，对象名是静态线索，必须重看本机窗口。主菜单或查询页没有 CoAP 监听不等于故障；“进入本地调试功能”、自检、开启日志上报属于不同的设备动作。不要提取程序内部鉴权信息或绕过 GUI 猜后台接口。

GUI 环境按以下次序检查：

1. 宿主是否提供原生 Windows 控制。只有浏览器能力时，不能操作 Windows 客户端；这是控制能力缺口，不是客户端未安装。
2. 当前目标窗口是否仍有效、位于可交互会话、可观察控件/截图；重新选择实际窗口后再输入，不沿用旧坐标或盲按回车。
3. 应用与控制器权限是否相容。已观察的移动视联 2.3.12 manifest 要求管理员权限，普通权限控制器可能无法输入；采用产品支持的权限方案，不修改 manifest 或绕过系统边界。
4. 控制宿主本身是否失败。曾出现 `failed to write kernel assets`、捕获超时与 `coordinate input geometry is unavailable`。恢复一个已准确定位的缺失临时目录曾恢复窗口文本读取，但未修复截图/点击，之后另一次运行时仍失败。此经验不是可普遍自动执行的修复脚本，不能猜目录或复制其他会话资产。

保存工作及原始错误后，可以按宿主支持方式重载相关运行时或重启应用，再复测；不能保证重启解决。相同权限窗口也发生过截图超时，移动视联权限差异不能解释全部故障。多显示适配器只有待查线索，不能据此禁用显卡、远控、显示驱动或改系统安全设置。未恢复控制时，转为人工界面操作加证据交接，并标注未完成 GUI 自动化。

## 10. 网站、登录与专用依赖

客诉系统、联楹（连楹）、移动视联采用“人工登录 → 观察业务页和目标权限 → 继续自动操作”。先连接使用者实际已登录的浏览器/客户端会话，不能打开一个新空会话后判断整台电脑未登录。账号、密码、验证码、短信及协议由使用者完成；代理不代填、不读取账号统计表、不导出 cookie。当前授权范围明确后，登录后的查询及取证无需逐步再确认。

报告分别写“等待人工登录”“登录状态未确认”“已登录但目标权限不足”“控制通道故障”。`queued` 的打开请求不是页面已显示；无法观察浏览器也不是登录失败。历史见过登录页仅说明当时入口可达，不保证当前权限。

老 DM、软探针、算法 OTA 与其他内部后台按实际产品、环境和文档配置。找不到入口/权限时只阻塞依赖它们的阶段，不拿客诉网站代替全部后台。路由器从当前测试环境明确入口，修改前保存参数并准备回读/恢复；能访问登录页不代表配置已验收。`firmware_encrypt` 仍需要符合原用例 SDK 版本要求的程序和说明，旧 SDK 或 Binwalk 都不能替代。

## 11. Artemis 1.5.2、MCP 与修复基线

本 Skill 不携带 Artemis 主程序、Python venv 或模型密钥。团队试用的可复现基线为 **Artemis v1.5.2，提交 `bdc75d0c657c5c2707b4c6e352eed6a1f5c14fff`，以及单独的观察任务修复补丁**。补丁适用性检查、应用与回退见 [Artemis 补丁说明](artemis-patch.md)；不得给其他版本盲套补丁，也不能仅更新 Skill 就认为 Artemis 已修复。

在批准的 Artemis 源码/发行目录中，按该版本 README 部署。1.5.2 的 Windows 正式入口为 `start.bat` / `start-cn.bat`，支持 `-SetupOnly`；这些脚本会检查或下载依赖并安装/更新 Codex MCP，属于环境变更，不是只读命令。已有可用环境则直接核对项目 venv、版本和配置，避免无因重装。

```powershell
Set-Location 'D:/TeamTools/Artemis'
.\start-cn.bat -SetupOnly
uv run artemis doctor
uv run artemis mcp --help
uv run artemis mcp --install codex
```

准备环境和手动 MCP 安装是按缺口选择的步骤，不要求每次都重复执行。由该项目生成本机 MCP 配置，使用项目 `.venv` 的 `python -m mcp_server` 或 `uv run artemis mcp`；不要分发开发者配置中的绝对路径。安装/更新后正常重载 MCP 或重启宿主，使新进程和工具签名生效。升级脚本会停止当前项目的服务、MCP 和任务，须在队列空闲且已保存工作时按版本说明使用；不能把升级当作运行中任务的无影响修复。

模型地址、Key 和模型名由使用者在 Artemis 本机设置或 `.env` 配置，不从聊天收集或写入 Skill。`mobile_workspace()` 核对 Android 设备和队列，首次调用 `mobile_diagnose(device_serial=...)`；仅认证异常才增加凭据验证，仅观察链异常才增加设备探测。诊断的修复选项可能重启 ADB 或调整设备锁，先根据真实失败和当前队列决定，不能习惯性全部开启。

scrcpy 诊断与实际录屏不一致时，先检查安装路径与长期驻留进程缓存。已知补丁补齐了标准安装路径；新进程识别成功后正常重载 MCP，不因旧进程仍报缺失就重复安装。ADB 设备未授权、离线、多实例或端口冲突按 doctor 的具体结果处理，不任意结束共享 ADB/模拟器进程。

最后以“只观察当前 APP 页面、保存实际文字和截图、正常结束并由 Checker 复核”的小任务验收连接。使用 [手机工作流](artemis-workflow.md) 的真实工具签名，显式选择设备；手机序列号与摄像机 SN 分开核验。历史补丁相关回归与一次真实只读观察已通过；完整源码测试仍有已记录失败，不能宣称全套通过。新电脑仍需完成自己的连接与样本任务验证，任务 `completed` 和目标级 `passed` 也不能扩展成多条摄像机业务通过。

## 12. 修复后的交接

仅记录本次实际改变：工具与版本、安装来源及摘要、解释器/DLL 位数、profile 字段、复测命令类别、执行状态、证据位置和未解决项。机器私有路径及设备资料留在本机运行记录，发布包只保留通用示例。不要带入开发机的原始日志、固件、pcap、截图、账号文件或历史任务报告。

按“运行时可用 → 本地样本通过 → 连接/登录就绪 → 业务断言取证”逐层交接。某个 GUI、平台或 SDK 仍阻塞时，继续已就绪且独立的工具环节；联合报告通过 [证据契约](evidence.md) 关联真实 Artemis 导出与外部材料，不改写原生 trace 或把环境修复成功写成业务用例通过。