docs: 新增《跨机接管的边界与局限》并记录真实故障诊断案例
皇上报障「Windows 上 WorkBuddy 反复提示 Response timed out」，要求记录 「受到什么局限导致 Mac 端无法修复 Windows 上的问题」。 新增 docs/REMOTE-LIMITS.md： - 能力边界总览（读状态/执行命令/改文件可；改网络高风险；GUI 与人工判断不可） - 五大核心局限：自断生路悖论 / 无 GUI 交互 / 无法替代人的判断 / 观测窗口时点性 / 破坏性操作不可逆 - 协作模式建议（能看能算的远程，断后路与需判断的交人工） - 真实案例（2026-09-27）：完整诊断链路与判读 本次远程诊断结论（未触碰 Windows 即完成）： - 链路正常：Ethernet 1Gbps/百度 200/腾讯 IPv4 200 - 矛盾状态：System Proxy ProxyEnable=0 但 ProxyServer 残留 127.0.0.1:10808 - 走 10808 访问外网超时 -> xray 上游节点不通 - resolveProxy RPC 耗时 1737ms（代理解析卡顿） - MarketplaceInitGate 15s 安全超时后强放行 判定高度可能为「代理配置残留 + 上游节点实际不通」导致部分请求超时； 未直接修复，因所需动作为 v2rayN GUI 换节点（属 GUI + 人工判断）。
This commit is contained in:
jkooe committed
1 parent
3316f08c92
commit
eb331502a6
2 files changed
+161
No files matched your search
@@ -324,6 +324,7 @@ nodeagent/
|
||||
|
||||
- [产品需求文档（PRD）](./PRD.md)
|
||||
- [开发文档（DEVELOPMENT）](./docs/DEVELOPMENT.md) —— 协议细节、能力 schema、安全模型、各端实现指南
|
||||
- [**跨机接管的边界与局限**](./docs/REMOTE-LIMITS.md) —— 哪些问题能远程修、哪些必须人工，附真实故障诊断案例
|
||||
|
||||
## 关键决策
|
||||
|
||||
|
||||
@@ -0,0 +1,160 @@
|
||||
# 跨机接管的边界与局限
|
||||
|
||||
> 本文记录 **Mac（控制端）能对被控端做什么、做不到什么**，以及为什么。
|
||||
> 素材来自 2026-09-27 对一台真实 Windows 机的诊断过程（案例见文末）。
|
||||
|
||||
---
|
||||
|
||||
## 一、能力边界总览
|
||||
|
||||
| 能力层级 | Mac 端可否 | 说明 |
|
||||
|---|---|---|
|
||||
| **读取状态** | ✅ 完全可 | 进程 / 服务 / 网络 / 文件 / 注册表 / 事件日志 —— 只要命令能查 |
|
||||
| **执行命令** | ✅ 完全可 | `system.shell.exec` 跑任意 PowerShell（管理员权限下） |
|
||||
| **改文件** | ✅ 完全可 | `fs.write` 原子写，可改配置 / 脚本 |
|
||||
| **改系统设置** | ⚠️ 多数可 | 注册表、服务、计划任务、防火墙规则等可用命令改 |
|
||||
| **改网络配置** | ⚠️ **高风险** | 能做，但**可能把自己弄断**（详见 §2.1） |
|
||||
| **操作 GUI** | ❌ 基本不可 | 鼠标键盘默认禁用，且即使开启也难判读界面状态（详见 §2.2） |
|
||||
| **需要人工判断的决策** | ❌ 不可 | 选哪个代理节点、订阅是否有效 —— 臣无从判断（详见 §2.3） |
|
||||
| **物理动作** | ❌ 不可 | 插拔网线、按电源键、换硬盘 |
|
||||
|
||||
---
|
||||
|
||||
## 二、核心局限（按严重程度排序）
|
||||
|
||||
### 2.1 「自断生路」悖论 —— 最根本的局限
|
||||
|
||||
**问题**：agent 自身**依赖网络**（Mac ↔ Windows 走 TCP 8765）。
|
||||
而被诊断的问题**往往正是网络**。此时若贸然修改网络配置：
|
||||
|
||||
```
|
||||
改网络配置 → 网络中断 → agent 连接断开 → Mac 彻底失联 → 无法回滚
|
||||
```
|
||||
|
||||
**具体危险操作**：
|
||||
- 禁用网卡 / IPv6 绑定（`Disable-NetAdapterBinding`）
|
||||
- 修改 IP / 网关 / DNS（`Set-NetIPConfiguration`）
|
||||
- 重启网卡（`Restart-NetAdapter`）
|
||||
- 修改防火墙规则（可能连 8765 一起挡了）
|
||||
- **重启系统**（重启后 agent 要等自启 + 网络恢复，期间完全失联）
|
||||
|
||||
**为什么不能靠「改完再改回来」兜底**：
|
||||
一旦断开，Mac 端**没有任何通道**能把配置改回去 —— 除非：
|
||||
1. Windows 侧有人在（那就失去「无人值守」的意义了）
|
||||
2. 或被控端配置了**计划任务自愈**（定时检查并恢复，属于后续可做的加固）
|
||||
|
||||
**缓解思路**（建议后续实现）：
|
||||
- **配置变更前自动备份** + **超时未确认则自动回滚**（类似路由器固件的「确认式配置」）
|
||||
- 关键网络操作走「两阶段提交」：先改、再 ping 验证、失败则回滚
|
||||
|
||||
---
|
||||
|
||||
### 2.2 无 GUI 交互能力
|
||||
|
||||
**问题**：`input.*`（鼠标键盘）出于安全考虑**默认禁用**；即使开启，臣也难以完成 GUI 任务。
|
||||
|
||||
| 场景 | 为什么做不到 |
|
||||
|---|---|
|
||||
| 代理软件换节点 / 更新订阅 | 需在 v2rayN 界面里点选，且**节点可用性关乎上游服务**，臣无法判断 |
|
||||
| UAC 提权弹窗 | 需人点「是」，agent 无法代点（安全设计） |
|
||||
| 安装向导（下一步 → 完成） | 界面状态判读不可靠 |
|
||||
| 浏览器登录 / 扫码 | 需要人的凭据与设备 |
|
||||
|
||||
**臣能做的替代**：用**命令行等价操作**绕过 GUI（如 `netsh`、注册表、服务命令）。
|
||||
但**第三方 GUI 软件的内部状态**（如 v2rayN 里"当前选中哪个节点"）通常没有命令行接口。
|
||||
|
||||
---
|
||||
|
||||
### 2.3 无法替代「人的判断」
|
||||
|
||||
有些问题**不是能不能执行，而是该不该执行**：
|
||||
|
||||
- 代理**订阅是否过期**、**节点是否可用** —— 需要人的账号与常识
|
||||
- 哪个软件该装、哪个进程能杀 —— 需要业务判断
|
||||
- 皇上看到的报错在**什么操作后出现** —— 臣无法感知复现路径
|
||||
|
||||
---
|
||||
|
||||
### 2.4 观测窗口的时点性
|
||||
|
||||
| 限制 | 影响 |
|
||||
|---|---|
|
||||
| 只能看**当下快照** | 间歇性问题（如抖动、偶发超时）容易漏判 |
|
||||
| 无法 7×24 盯 | 臣只在被调用时"看一眼"，问题在两次调用之间发生就看不到 |
|
||||
| 应用层内部状态不可见 | 如 WorkBuddy 的"当前正在等哪个请求"，臣只能从日志反推 |
|
||||
|
||||
**缓解**：可让被控端**持续采样并落盘**（如每分钟记录一次网络状态），事后由臣分析。
|
||||
本项目已有 `system.shell.exec` + `fs.write`，具备实现基础。
|
||||
|
||||
---
|
||||
|
||||
### 2.5 破坏性操作的不可逆
|
||||
|
||||
- **删文件**：`fs.write` 是覆盖写，无回收站语义
|
||||
- **改注册表**：无版本控制
|
||||
- **改服务/任务**：原配置不保留
|
||||
|
||||
**缓解思路**：所有写操作前**自动备份到带时间戳的副本**（可作为后续加固项）。
|
||||
|
||||
---
|
||||
|
||||
## 三、协作模式建议
|
||||
|
||||
| 类别 | 交给 Mac 端远程 | 必须人工 |
|
||||
|---|---|---|
|
||||
| 状态诊断（进程/服务/网络/日志） | ✅ | |
|
||||
| 执行命令、改文件、改配置 | ✅（需评估断网风险） | |
|
||||
| 网络配置变更 | ⚠️ 仅在**有回滚保障**时 | 无保障时人工 |
|
||||
| GUI 软件操作（代理客户端等） | | ✅ |
|
||||
| 需要账号/凭据/判断的决策 | | ✅ |
|
||||
| 重启、物理操作 | | ✅ |
|
||||
|
||||
**一句话**：**能"看"和"算"的尽量远程，涉及"断自己后路"和"需要人判断"的交给人工。**
|
||||
|
||||
---
|
||||
|
||||
## 四、本次真实案例（2026-09-27）
|
||||
|
||||
**报障**：Windows 上的 WorkBuddy 反复提示 `Response timed out (no data received). Retrying automatically...`
|
||||
|
||||
**诊断手段**：全程经 nodeagent 从 Mac 远程执行，未触碰 Windows。
|
||||
|
||||
**查到的关键事实**：
|
||||
|
||||
| 观察项 | 结果 | 判读 |
|
||||
|---|---|---|
|
||||
| 网络适配器 | Ethernet Up / 1 Gbps | 链路正常 |
|
||||
| 国内网络（百度） | HTTP 200 / 0.24s | 基础联网正常 |
|
||||
| `copilot.tencent.com` | HTTP 200 / 0.35s（IPv4） | 后端可达 |
|
||||
| v2rayN + xray 进程 | 均在运行 | 代理软件活着 |
|
||||
| xray 监听 | `0.0.0.0:10808` | 代理端口在听 |
|
||||
| **系统代理** | **`ProxyEnable=0`，但 `ProxyServer` 残留 `127.0.0.1:10808`** | ⚠️ 配置矛盾 |
|
||||
| 走 10808 访问外网 | 超时（HTTP 000 / 20s） | ⚠️ **上游节点不通** |
|
||||
| **`resolveProxy` RPC** | **耗时 1737ms（慢）** | ⚠️ 代理解析卡顿 |
|
||||
| **MarketplaceInitGate** | **15s 安全超时后强放行** | ⚠️ 启动期被拖慢 |
|
||||
| WorkBuddy 连接 | 4 条 IPv6 到腾讯（已建立） | 部分链路正常 |
|
||||
| TCP `CloseWait` | 24 条 | 偏多，疑似连接被中途中断 |
|
||||
|
||||
**结论（高度可能）**：
|
||||
系统存在**「代理配置残留但未启用，且 xray 上游节点实际不通」**的矛盾状态 ——
|
||||
WorkBuddy 解析代理慢 + 部分请求走了不通的代理链路 → `Response timed out`。
|
||||
|
||||
**为什么臣没有直接修**：
|
||||
- 需要的动作是「在 v2rayN 界面换可用节点 / 更新订阅」→ **属 GUI + 人工判断**（§2.2 / §2.3）
|
||||
- 若改为「清空系统代理残留」→ 属网络配置变更，虽有价值但**需皇上确认**（§2.1 风险）
|
||||
|
||||
**建议的下一步**（人工为主）：
|
||||
1. 打开 v2rayN → 测试节点延迟 → 换一个可用节点（或更新订阅）
|
||||
2. 确认 v2rayN 的「自动配置系统代理」策略与实际需求一致
|
||||
3. 观察是否仍有 `Response timed out`；若仍有，可让臣**持续采样**再定位
|
||||
|
||||
---
|
||||
|
||||
## 五、结论
|
||||
|
||||
**nodeagent 的定位不是"替代人"，而是"把人从重复的状态检查与命令执行里解放出来"。**
|
||||
|
||||
- 它擅长：**可观测、可脚本化、无副作用**的事 —— 诊断、查询、批量执行
|
||||
- 它回避：**断后路、需判断、需凭证**的事 —— 这是设计取舍，不是缺陷
|
||||
|
||||
明确这条边界，才能既用好它，又不至于在关键故障时**因为"以为能远程修"而耽误时间**。
|
||||
Reference in new issue
Block a user