# 0.2.0 托管集成版验证说明

验证日期：2026-10-27（Asia/Taipei）。运行环境：Linux，Node.js v24.22.1。

## 实际运行结果

| 检查 | 结果 | 实际覆盖 |
| --- | --- | --- |
| `npm test` | **36 通过，0 失败** | 消息通道、安装器、配置生成、进程所有权与生命周期；Agent/模型使用测试替身 |
| `npm run test:contracts` | **2 通过，0 失败** | 使用实际安装的公开 `dsh-tools@0.2.1-rc.4` JSON Schema 实现，以及 `dsh-llm@0.2.1-rc.4` 消息工厂 |
| `npm run check` | 通过 | 全部项目 `.mjs` 模块的 Node 语法检查 |
| `npm run test:browser` | **1 跳过，0 执行** | 环境中无 Chromium 可执行文件，未执行浏览器交互 |
| 官方 NapCat 运行包下载 | **通过** | 实际下载 `v4.18.41 / NapCat.Shell.Windows.Node.zip`，共 124089498 字节 |
| 官方包 SHA256、真实 ZIP 解压 | **通过** | 摘要与固定 Release 元数据一致；检查 Node、QQ 原生组件、入口及 NapCat 文件均存在 |
| Windows 原生引擎启动与扫码 | **未执行** | 当前环境为 Linux，没有运行下载包中的 Windows 可执行文件 |
| 真实 Harness 桌面／Web 安装 | **未执行** | 本环境没有用户的 Harness 安装与配置 |
| 真实 QQ 收发、历史与空间留言 | **未执行** | 没有登录用户 QQ 或 QQ 空间 |

尝试运行 `npx playwright install chromium` 时，浏览器下载返回无效／不完整的压缩文件，最终安装失败。因此不能把浏览器测试或真实 QQ 空间适配称为已通过。Windows 默认使用用户已安装的 Edge，无需依赖本测试环境的 Chromium 下载结果，但仍须在目标机器验收。

本版总计 **38 项本地／接口契约测试通过**，浏览器测试 1 项跳过。宿主契约依赖单独安装在测试目录，使用 `DSH_CONTRACT_ROOT` 指向该目录执行，未修改正式 Harness profile。

## 36 项核心测试

1. 校验 QQ 号、本机地址、访问配置、回复模式与密钥长度。
2. 私聊和群聊白名单、禁用与屏蔽项分别生效。
3. 空间 URL 只由合法 QQ 号与允许的页面类型构造；未知响应不冒充成功。
4. 并发限制在竞争下不超过设置值。
5. 组合链路：签名 HTTP 入站 → 隔离 Agent → 带 Bearer 的 HTTP 发送 → 持久归档；重放不再次发送。
6. 不同私聊、群聊隔离；群聊按 @ 唤醒；重复事件、自身回声不触发回复。
7. 同一会话多条消息按顺序处理。
8. 普通联系人不能列出好友、读取其他会话、调用 shell 或在空间留言。
9. 管理员工具权限只作用于传输层确认的管理员私聊，群内身份声明无效。
10. 回复队列满时仍归档入站消息，只跳过自动回复。
11. 被禁用的会话不归档、不回复。
12. 即使绕过 JSON Schema 直接调用，仍拒绝未知参数、空文本和无效操作标识。
13. 只转发最终文本，不转发思考内容、工具调用草稿或失败／中止回合内容。
14. 归档跨重启去重；按会话、关键词查询。
15. 并发重复操作和重启后的重复操作不会再次发送；操作标识不能用于不同内容。
16. 网络结果不明确时保存 `uncertain`，相同操作不会自动重试。
17. 同一数据目录不能同时启动两个运行实例。
18. 验证 Webhook 签名，拒绝被篡改、未签名、超限或路径错误的请求。
19. 丢弃错误登录号、缺少消息 ID、自身回声与非消息事件；媒体不泄露原始资源 URL。
20. 使用真实本机 HTTP 服务验证 API Bearer、纯文本消息段、账号核对、retcode 失败与历史序号字符串。
21. 超时会取消延迟的 HTTP 请求。
22. ZIP 路径检查拒绝目录穿越、Windows 盘符、备用数据流和保留文件名。
23. 运行包大小、SHA256 均需匹配，才可继续安装。
24. 下载可跟随 GitHub 资产跳转，拒绝其他主机。
25. 不完整下载不会进入可复用缓存。
26. 使用真实 ZIP 字节测试解压，拒绝符号链接与大小写冲突路径。
27. 完整测试运行包经校验后解压，重复安装复用已有版本。
28. 安装取消后不留下部分下载或安装锁。
29. 自动生成账号专用 OneBot、事件签名和 WebUI 配置，重复运行不累加，保留其他设置。
30. 认证正确的外部 NapCat 可复用，不改配置、不停止其进程。
31. 管理器以参数数组启动自有真实测试子进程，确认登录后只结束该进程。
32. API 或 WebUI 端口冲突时不启动新进程，并释放自己的锁。
33. 等待扫码时可查看状态，发送及其他业务工具暂不可调用。
34. 在管理器异步启动期间退出会等待启动工作收敛，不遗留进程所有权锁。
35. 在消息桥异步启动期间退出不会留下数据锁或在线状态。
36. 引擎意外退出后遵守重启预算，不无限重启。

进程测试在 Linux 启动受控的 Node 测试子进程，验证所有权、参数与清理行为；没有把它描述为 Windows QQ 引擎验收。

## 实际官方包核对

运行了本项目的 `installNapcat` 下载与解压流程，目标规格为 Windows x64，但没有执行包内二进制。实际下载摘要：

```text
asset: NapCat.Shell.Windows.Node.zip
version: v4.18.41
bytes: 124089498
sha256: 51fbb10e7bcd56b0c2a6de86c37811e7518330e48a137ac689ab1e4d8627d3f0
```

已确认包内 `node.exe`（Windows MZ 文件）、`index.js`、`wrapper.node`、`QQNT.dll`、`package.json`、`config.json` 和 `napcat/napcat.mjs` 与安装器要求的布局一致。另核对官方源码的 `NAPCAT_WORKDIR` 和 `onebot11_<QQ号>.json` 规则。

## 宿主契约检查的边界

两项检查确实加载了公开 npm 包的实现，而不是重写一个相似验证器。它们确认 8 个工具的输入／输出 JSON Schema 在该版本的支持范围内，以及消息工厂生成带固定身份、角色和不可变内容的 UserMessage。

它们没有启动完整 Harness Agent driver、没有调用真实模型，也没有验证所有桌面版本的本地包安装入口。目标版本升级后须重新验证插件加载与 Agent 生命周期。

## 目标机器验收顺序

1. 新安装执行 `setup`；旧配置执行 `napcat-enable`，准备固定官方运行包。
2. Harness 加载后自动启动 NapCat 并弹出扫码页，完成指定 QQ 号登录。
3. `doctor` 核对 NapCat 登录号和只读接口。
4. 在 Harness 调用 `qq_status`，确认已在线。
5. 另一个 QQ 号发私聊，确认回复只回到该私聊。
6. 群内不 @ 时只归档，@ 后回复；确认群上下文不含其他私聊。
7. 查询本地及 QQ 历史，确认记录范围与分页序号。
8. 只在自己的或同意测试的好友空间试一条留言，核对真实页面结果和工具回执。
9. 同一 `request_id` 再次调用，确认没有新增第二条消息或留言。
10. 退出 Harness，确认只关闭本插件托管的 NapCat；原有外部实例不受影响。

这份清单是运行验收步骤，不代表上述真实账号测试已经执行。