用途与实际影响
这项功能怎样使用
为什么需要它
跨子网时 KDE 广播发现可能找不到另一台电脑。明确对端地址能让 KDE 主动探测；组网故障和应用配对仍要分开判断。
举个实际例子
“帮我确认这两台已登记的电脑能不能联系到，先不要传文件。”AI核对选中的两台设备和它们的连接地址，再检查指定连接；交回哪一端可达、哪一段失败和依据。能联系到电脑还不代表剪贴板或文件传输已成功。
最后我会得到什么
得到准确对端地址及连通性诊断，供后续配置使用；ping成功不是剪贴板和文件验收。
正常时
两台指定电脑都已加入同一 Tailscale 网络并在线，诊断确认能找到对方；文件传输和 KDE 配对仍另验。
发现问题时
有多台可能的电脑却没指定目标，或对端离线时停止自动选择，请本人确认要连哪台。
入口不可用或证据不足时
Tailscale 未运行或本人尚未通过官方网页登录时，先完成这一步，不尝试绕过身份。
从哪里开始
两台 Windows 电脑分别运行 scripts/install-windows.ps1，经官方浏览器登录；再运行 scripts/configure-peer.ps1 -Peer 指定准确对端，用 scripts/doctor.ps1 查可达性。
需要准备什么
- 要互连的两台 Windows 电脑
- 本人通过官方浏览器完成 Tailnet 登录
从开始到拿到结果
- 1
两端上线
核对 Tailscale 服务、本机在线和无人值守设置；脚本不会替人登录。
- 2
选准对端
输入准确设备名并检查它在线，避免把相似设备当目标。
- 3
单独测网络
doctor 做有界 ping，报告直连、中继或不可达；网络通过仍要另做 KDE 配对。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
本机网络与批准对端 ping 通过关键规则与设计选择
同一Tailnet中的批准设备才进入配置流程；直连失败可用Tailscale中继，不承诺零公共中继。
自动选择只有一个在线Windows对端时成立；显式名称必须精确匹配。
使用官方浏览器登录，不传递脚本内登录密钥；对端身份在诊断中脱敏。
本模块用到的名词
- Tailnet（Tailscale 虚拟网络）
- Tailscale 账户下的所有授权设备组成的专属点对点加密网状网络。
- Run Unattended（无人值守）
- Tailscale 无人值守服务模式，无需用户手动打开客户端界面即可在后台自启保持在线。
专业定义
跨网络加密隧道与单对端安全发现
解决什么
若 Tailscale 未登录、处于 Shields Up 模式，或存在多个同名/离线设备导致无法安全辨别目标，脚本拒绝盲目猜测并终止执行。
当前怎样实现
- Get-MeshClipTailscaleStatus 安全解析 tailscale status --json 输出。
- Resolve-MeshClipApprovedWindowsPeer 校验对端状态、系统类型与唯一性。
- ConvertTo-MeshClipRedactedAddress 提供确定性单向掩码脱敏转换。
执行流程
- 1
检查服务自动运行、BackendState=Running、本机在线。
- 2
检查ForceDaemon与shields-up；不自行改动不符合条件的现状。
- 3
解析明确对端，确认在线且为Windows。
- 4
doctor执行一次有界tailscale ping，结果独立于KDE配对。
边界
- 仅负责底层 Tailnet 隧道的打通与对端 IP 的精准析取，不负责上层 KDE Connect 的配对确认。
- 严格仅支持经过官方浏览器认证的个人 Tailnet，绝不在脚本中传递明文 auth-key。
失败与恢复
- 对端设备关机或离线
- Resolve-MeshClipApprovedWindowsPeer 抛出错误拒绝继续，提示开启对端电脑。
- Tailscale 开启了 shields-up
- doctor 诊断标记 FAIL 并提示关闭入站拦截以允许 KDE Connect 流量进入。
真实入口
scripts\MeshClip.Common.psm1Tailscale 状态与对端解析核心逻辑
scripts\configure-peer.ps1对端配置入口脚本
tests\MeshClip.Common.Tests.ps1地址脱敏与对端解析单元测试
如何验证
- 本轮源测试验证精确名称匹配、离线/非Windows拒绝、多对端歧义与地址脱敏。
- 本轮Tailscale服务、在线、无人值守、入站设置、批准对端与ping检查通过。
与其他模块的关系
为KDE对端配置提供明确的网络地址和可达证据，不替代应用层确认。